QuantiTeam

About

The abstract below has been taken from my MSc thesis paper QuantiTeam: Blockchain architecture as a medium to verify collaborative work. The full paper is available in PDF format here.

The ability to work proficiently in collaboration with others is highly valued within a large number of social contexts. Yet, a person’s ability to do so is scarcely quantifiable in any meaningful way. The goal of this project was therefore to examine the feasibility of constructing a system which can verify and quantify collaborative work. The project was set in the specific context of attempting to solve student disengagement, as the larger concept arose from this concrete problem.

The project attempts to provide a high level of potential for true verification and quantification of collaborative data by utilising a distributed data structure known as a blockchain. Following an analysis of how the proposed system could be structured in terms of interactions between a client and the blockchain, an API was constructed to provide as much functionality as was feasible within the time available. Additionally, a simple client-side mobile application was developed to showcase the API’s functionality in a concrete manner.

While the project falls short of establishing a manner to truly verify and quantify collaborative work with a distributed blockchain, it demonstrates that such an endeavour is certainly feasible given more time and expertise in the topic area, thus providing a basis for future work to create a bona fide system for verification and quantification of team work.

Installation

Dependencies

The following dependencies are required to run a local development instance of QuantiTeam's Tendermint blockchain:

• Docker CLI - docker (& docker-machine on OSX).
• Eris CLI - eris provides a wrapper and toolchain around the Tendermint blockchain and is used extensively.
• Node.js - v4.x upwards.
• NPM - QuantiTeam relies on NPM scripts to run tests and various other tasks.

To install the project's Node.js dependencies, ensure your present working directory (pwd) is quantiteam/chain and run:

npm install

Setting up

First, let's move into QuantiTeam's API directory with the following command:

cd chain

Creating a local dev simplechain:

• Automatically: Run . ./simplechain.sh in the repository's root directory, which should start logging the chain's activities after setup.
• Manually: Follow Eris's brief tutorial.

Running a local development chain

Assuming we now have a functioning simplechain instance, let's boot it up and configure some local environment variables. In the repo's root directory run the following two shell scripts:

. ./chain-up.sh; . ./envsetup.sh

We can easily verify whether the simplechain instance is running as expected by following its log output:

npm run chainlog

Running the Node.js chain service

Now that we have a local development chain running which we can interact with, let's spin up the chain service which will act as our API router to interface with the local chain itself.

Deploying contracts

First, let's compile and deploy our Solidity smart contracts in the contracts directory:

# `$addr` should be defined from previously running `envsetup.sh`
npm run compile -- $addr

Anytime a change is made to the smart contracts, compile should be run to deploy these changes to the running simplechain instance.

Running tests

Next, we'll want to run QuantiTeam's test suite to ensure everything is working as expected:

npm test

This should also provide a coverage report once all unit tests have run.

Booting the service

The chain service itself can be built & booted simply with:

npm run build

Anytime a change is made to the node server, build should be run as it builds a new service container via docker and replaces it with the previous one via eris.
Please refer to package.json for more detailed insights into which shell commands each NPM script executes.

API

QuantiTeam's API exposes the following HTTP endpoints:

Stable

Users

/user/taken

• Description: Checks whether the the username in req.body.username is already taken. Returns a boolean.
• Method: POST
• Request body:

{
    username: string
}

• Response:

{
    isTaken: boolean
}

/user/signup

• Description: Signs up a new user with the credentials in req.body.form. Returns the new User contract's hex address.
• Method: POST
• Request body:

{
    form: {
        name: string,
        email: string,
        username: string,
        password: string
    }
}

• Response:

{
    address: string // hex address
}

/user/login

• Description: Logs in an existing user with the credentials passed in req.body.form. Returns isValid boolean to signify validity of credentials, and a user object if the login was successful. Additionally a team object is returned if the user is part of a team.
• Method: POST
• Request body:

{
    form: {
        username: string,
        password: string
    }
}

• Response:

{
    isValid: boolean,
    user: {
        name: string,
        username: string,
        score: string,
        teamname?: string,
        email?: string,
        address?: string
    },
    team: {
        name: string,
        score: number;
        members: Array<User>,
        founderUsername: string,
        founderAddress: string, // hex address
        address?: string
    }
}

Note

• user & team props will be null if isValid === false.
• team prop will automatically be null if the user is not part of a team.

/user/profile/:username

• Description: Gets the profile of the username passed via req.params.username. Returns a profile object.
• Method: GET
• Request: /user/profile/johndoe
• Response:

{
    profile: {
        name: string,
        username: string,
        score: string,
        teamname?: string,
        email?: string,
        address?: string
    }
}

Tasks

/tasks/:username

• Description: Gets the tasks of the username passed via req.params.username. Returns an array of Task-type objects. Returns an empty array if :username param has no tasks associated with it.
• Method: GET
• Request: /tasks/johndoe
• Response:

{
    data: Array<Task>
}

/task

• Description: Adds a new task to the blockchain via the form data passed in req.body.task for the username in req.body.username. Returns a boolean indicating whether a previously existing task was overwritten, along with the task's hex address.
• Method: POST
• Request body:

{
    username: string,
    task: {
        id: string,
        title: string,
        desc: string,
        reward: string,
        complete: string,
        status: "To Do" || "Completed" // enum
        participants: Array<string>,
        creator: string,
        token: string,
        createdAt: number // unix timestamp
    }
}

• Response:

{
    isOverwrite: boolean,
    taskAddr: string
}

/task/completed/:token

• Description: Marks the task associated with the token passed in req.params.token as completed. Returns a boolean indicating whether marking the task was successful.
• Method: GET
• Request: /task/completed/xyz123
• Response:

{
    success: boolean
}

Teams

/team/taken/:teamname

• Description: Checks whether the teamname passed as req.params.teamname is already taken. Returns a boolean indicating whether the team name is already taken or not.
• Method: GET TODO

/team

• Description: Adds a new team to the blockchain via the form data passed in req.body.form. Returns the new team's hex address in the blockchain and a boolean indicating whether the team was successfully linked to it's founder in the blockchain.
• Method: POST
• Request body:

{
    form: {
        name: string,
        founderUsername: string,
        founderAddress: string, // hex address
        createdAt: number // unix timestamp
    }
}

• Response:

{
    address: string, // hex address
    linkSuccess: boolean
}

/team/:teamname

• Description: Gets the team profile for the teamname passed as req.params.teamname. Returns a Team-type object.
• Method: GET
• Request: /team/myteamname
• Response:

{
    name: string,
    score: number,
    members: Array<User>,
    founderUsername: string,
    founderAddress: string,
    address: string // hex address
}

/team/add-member

• Description: Adds a new member to a team with the form data passed in req.body.form. Returns a boolean indicating whether the passed username was successfully linked to the team, along with an indicator of whether the username actually exists.
• Method: POST
• Request body:

{
    form: {
        username: string,
        teamname: string,
        teamAddress: string // hex address
    }
}

• Response:

{
    isTaken: boolean,
    username: string,
    linkSuccess: boolean
}

Experimental

• POST /upload - Upload a task related file via multipart/form-data.

Shutting down

To shut down the local chain and the docker-machine instance, simply run:

. ./chain-down.sh