ribbonblockchain / incentivesalpha

JavaScript tools and applications that interact with RibbonBlockchain smart contracts

API CI:

Front End CI production:

Front End CI staging:

Home page: ribbonblockchain.com

Staging: dapp-staging.ribbonblockchain.com

Production: dapp.ribbonblockchain.com

---

Ribbon Blockchain is a healthcare incentives platform that aims to modify health and wellness behaviour through rewardable tasks.

Ribbon channels donated, pledged or sponsored funding directly to patients, community health workers and healthcare practitioners; where such funding is used to incentivize preventative care, adherence to medication and therapy, quality of care delivery and overall population health outcomes.

Our Incentives are distributed in DAI, an asset-backed, decentralized stablecoin on the Ethereum blockchain.

Table of Contents

• Table of Contents
• Packages
• Requirements
• Getting Started
• Contributing
• Resources

Packages

This monorepo contains JavaScript tools and applications that interact with RibbonBlockchain's smart contracts. The ribbon platform consists of 3 key components right now. this will change in time. These are as follows:

Name	Description
@ribbonblockchain/api	Backend API built with Node, typscript express restful API that handles data capture for patients and all system wide interactions.
@ribbonblockchain/frontend	Frontend react application that patients, CHW, practitioners and admins interact with. Link
@ribbonblockchain/blockchain	Solidity Smart contracts that control the funding distribution, allocation and assignment within the Ribbon ecosystem.

Each section has it's own package and has it's own readme within the package that explains how to set it up and get running with that spesific component.

Requirements

This project requires node >=10.0.0 and yarn >=1.0.0. A unix shell is also required.

• Installing Node
• Installing Yarn
• UNIX Shell (Windows users)

Getting Started

To get started, clone the repo and install its dependencies:

git clone https://github.com/RibbonBlockchain/IncentivesAlpha.git
cd IncentivesAlpha
yarn

For development purposes there's a top-level start script that will watch and continuously compile all packages concurrently:

yarn frontend:start

For next steps, take a look at documentation for the individual package(s) you want to run and/or develop. Each package can be run from the root directory using Lerna. The main things you can do are outlined below:

    yarn frontend:start         # start run the front end server
    yarn frontend:build         # build front end for production

    yarn contracts:build        # compile the smart contracts
    yarn contracts:deploy:local # deploy smart contract to local ganage instance
    yarn contracts:deploy:sokol # deploy contract to sokol test POA network
    yarn contracts:start        # start a local ganache-cli instance
    yarn contracts:test         # run contract unit tests
    yarn contracts:cover        # generate coverage report

    yarn backend:test           # run API unit tests
    yarn backend:build:         # build API for production
    yarn backend:dev            # start API in development mode
    yarn backend:prod           # start API in production mode

Contributing

Thanks for your interest in RibbonBlockchain. There are many ways you can contribute. To start, take a few minutes to look over the official guide:

Read the "Contributing to RibbonBlockchain" Guide »

We happily await your pull requests and/or involvement in our issues page and hope to see your username on our list of contributors 🎉🎉🎉

Resources

To get a full idea of what RibbonBlockchain is about, be sure to take a look at these other resources

1. Website
2. Alpha DApp
3. Twitter

incentivesalpha's Issues

Create Interactions tab dashboard default fields arranged as follows: Interaction, Patient, Practitioner, Health Worker, Total Tokens sent, Date

Sprint 4

This sprint builds the initial reporting functionality that we require to generate patient reports. Mobile optimization and front end styling is also done in this sprint.

User wallet functionality

Every user within the application has a wallet! they should be able to view their balances (as discussed in issue #49) within a small card above the table. somewhere in the application in an obvious place (for example in the menu bar) there should be a button that opens up a modal to control the wallet. this should have the following functionality:

• Send tokens to address
• scan QR code
• view wallet QR code

Implement API endpoints to generate reports

This issue aims to outline the beginning part of what we need for reporting. @GuguNewman had identified what is required within the endpoints. This issue is to create the endpoints to generate the json payload for each of the kinds of reports outlined below.

Sprint 3

Refine and improve sprint 2, add additional functionality and continue it moving 🕺

Change Interactions tab dashboard content text colour from white on white to grey/black on white (front-end / styling)

Superuser dashboard (creating users)

Superuser dashboard

The dashboard the superuser is direct to once connecting to the dapp.

Acceptance criteria

• The superuser has buttons to create a: CHW/patient/practitioner (interacts with the contracts)
• The superuser may search for a CHW/patient/practitioner by address, and once the user has been found they can:
• Update a CHW/patient/practitioner information (not address) (all database information)
• Delete the CHW/patient/practitioner (blacklists on contracts)

Technical Implementations/notes

• These calls to the database should be authenticated via a signed message from the super user's wallet. We can then check from the database if that address is assigned super user status.

Supporting documents

@chrismaree

CHW dashboard (activities and views)

CHW dashboard (activities and views)

Once the CHW has connected to the dapp and directed to this dashboard.

Acceptance criteria

• The CHW can see their balance
• The CHW can see their relevant TX (the activities they took part in)
• The CHW can record activity by pressing a button that says "record patient activity". This opens a model where the CHW can select from activities the superuser has added, can either scan the QR code of a patient and practitioner or search for them by name. The cancel button is on the left, and the "record" is on the right. Clicking record will create a transaction
• The CHW can see the transaction mining and is notified when it had finished mining.

Supporting documents

Screenshots of the app now with drawings of what it should look like after, architecture designs, etc.

Sprint 2

Wallets

This epic is the onboarding of patents and practitioners into the ribbon system

Patient creation

The patient has a wallet that they can use to log into the Ribbon system

1. The community health worker creates a profile for the patient
2. The patient goes into the Ribbon dapp and (as they do not have an unlocked wallet) is presented with a button that allows them to create a wallet. It will then display a QR code.
3. The CHW scans this QR code and the patient's details are now linked to their wallet.
4. The QR code disappears off the patents phone and they can now use the dapp.

Practitioner creation

The practitioner has a wallet that they can use to log into the Ribbon system

1. The community health worker creates a profile for the practitioner
2. The practitioner goes into the Ribbon dapp and (as they do not have an unlocked wallet) is presented with a button that allows them to create a wallet. It will then display a QR code.
3. The CHW scans this QR code and the practitioner's details are now linked to their wallet.
4. The QR code disappears off the practitioner's phone and they can now use the dapp.

Initial Contracts

Contract architecture

Acceptance criteria

Admin Contract

• Using AdminWhitelist from Openzeppelin
• Can whitelist accounts in the Registry (adding removing CHW, practitioners and patitents)
• Has kill switch for all contracts

Registry Contract

• Stores a mapping of whitelisted addresses (along with their role (enum))
• Stores the last time that an address got paid out

CHW Access Contract

• Allows a CHW to submit a payout request
• Rate limits (via the doctors address (cooldown))
• Can be shut down by the Admin contract (will fail if a CHW tries to make a payout)

Funding Vault Contract

• Holds funding
• Can be switched off by the admin contract
• Has a max payout (i.e, each payout can only be for x amount) this can be changed by the admin contract

Sprint 4 refinement

Add new user modal text is inconsistent.

1. When you open the modal right now it says
   "add administrator"
   "community healthcare worker profile". these should be in the same tense and should be consistent.
2. Error messages in the top bar should be close automatically after rendering.
3. Record interaction modal should be portrait

Sprint 1

CHW

This Epic is for creating the CHW dashboard, as well as the superuser to create CHW.

Superuser

A superuser is added to the contracts by the contract deployer address

The superuser can:

• Add and remove CHW
• Add and remove patients
• Add and remove practitioners

CHW

The CHW needs to be able to create profiles for other users (in this sprint they should only be able to enter the details for the user, as well as the user's role. Dummy addresses will be used in this sprint to create the patients/practitioners and will be replaced in the next sprint).

1. The CHW can choose between adding a patient or a practitioner
2. The CHW enters the relevant information for the user
3. The CHW then hits create and a user is created in the contracts
4. The model then closes and the CHW is back on a blank dashboard with a button to create a practitioner and a button to create a patient.

patient dashboard (views)

patient dashboard (views)

Once the patient has connected to the app they are directed here

Acceptance criteria

• The patient can see their balance
• The patient can view their related TXs (the actions that they took part in)
• The patient can report an activity (they were incorrectly added to a TX) (this does not remove funding from their account)

Technical details

@chrismaree

Supporting documents

@chrismaree

CHW dashboard (contract & blockchain interaction)

CHW dashboard (contract interaction)

When a CHW creates a patient or practitoner this interaction and creation is stored on the contracts.

Acceptance criteria

• When a CHW creates a patient or practitioner, they scan a QR code on the patient or practitioners phone
• Once they have scanned the code, a transaction is generated and executed against the contracts to create a patient/practitioner (information pulled from the form)
• The CHW can see when the transaction is mining
• The CHW can see when the transaction has been mined
• The model to create the patient or practitioner closes
• At this point an API endpoint is called to store the patient information
• This API end point should respond when data is stored in DB

Technical Implementations/notes

@chrismaree

• contract's will be done before this integration starts.
• API should be called registerPatient or RegisterPractitioner depending on the context
• API doc scheme should be well defined.

Supporting documents

@chrismaree

Refined smart contract & Add unit tests

Right now our contracts dont have enough test coverage and this needs to be improved

Sprint 5

Styling and product refinement

Transaction tracking and processing

• Transaction tracking that tells you when a block has been found and tx mined. I want a popup when the tx is mined + a link I can click when it's submitted to Sokol.
• I want to see transaction errors posted as a popup.

For this pick a nice popup library.

Phone number and CHWE number validation

The API should validate the all input data such as checking if a number has been used before and if the CHW number is unique.

Create page on landing page to enable public to donate to Ribbon's ecosystem.

This should go to a multisig wallet.

Catch when user wallet is locked and tell user to unlock it

if the user's wallet is locked tell them to unlock it. current wallet status freezes if not unlocked.

once unlocked fix app. right now when it unlocks the routing breaks.

Move instances of contracts to pull from build directory instead of from environment variables

Right now we pull contract addresses from env. this should come from the build rather.

User specific cards above table

Wallets need to add a number of user specific cards to show key information for different user groups.

Admin ones are fine for now.

CHW:

• Number of patients seen today
• Number of patients seen last week
• total patients onboarded

Practitioner:

• Number of patients seen today
• Number of patients seen last week
• Incentives earned to date

Patient:

• number of visits
• incentives earned

@GuguNewman please comment below if you want this to change to anything else.

This issue will require input from both @iamonuwa and @KapsonLabs to finish it as API endpoints are required

CHW Dashboard

Acceptance criteria/definition of done

CHW Dashboard

After a CHW has connected to the dapp and logged into the dapp and has been directed to the CHW dashboard

Acceptance criteria

These should describe the functionality of the repo after all the work is compleat

• There are 2 buttons on the screen, "Add Patient" and "Add Practitioner"
• When the "Add Patient" button is clicked, a model pops up (taking up the entire screen)
• At the bottom of the model on the left is a cancel button, and on the right (in line with the cancel button) is a "Add Patient" button.
• The model has text fields (the same as P1's model) for the patient's information
• When the CHW clicks cancel, they are re-directed to the dashboard
• When the CHW clicks "Add Patient" the patient details are then stored in a database (no blockchain or API interactions right now)
• When the "Add Practitioner" button is clicked, a model pops up (taking up the entire screen)
• At the bottom of the model on the left is a cancel button, and on the right (in line with the cancel button) is a "Add Practitioner" button.
• The model has text fields (the same as P1's model) for the practitioner's information
• When the CHW clicks "Add Practitioner" the patient details are then stored in a database (no blockchain interactions right now)
• Once the user has been created the model closes and the CHW is re-directed to the dashboard with the 2 buttons

Technical Implementations/notes

• No API or contract interactions are to be done in this ticket.

Supporting documents

@chrismaree please add wireframes

User transaction tables

For all user groups we need to see the transactions that have been processed.
This should include the payment amount, the activity done and the CHW that was involved in this.

This will require pulling from the API for the respective endpoints to get info for diffrent users.

This will differ based on the user. For CHW there will be slightly more info, patient slightly less info. @GuguNewman will add more details as to what columns should be here for each user group.

Practitioner dashboard

Practitioner dashboard

After the practitioner has connected to the Ribbon dapp they are directed here. In this dashboard, they can interact with their funds, see balances etc.

Acceptance criteria

• Can view all transactions that their address was in (all actions)
• Can report a transaction (if they were incorrectly added to a transaction
• View their balance
• View their rating (an average of all their ratings)

Technical details

@chrismaree

Supporting documents

@chrismaree

Log in

Log in

A user with a web3 enabled browser goes to the Ribbon dapp.
The blank dashboards will be filled in at a later stage.

Acceptance criteria

These should describe the functionality of the repo after all the work is compleat

• The user is requested to unlock/connect their wallet
• The user address is checked against the contracts
• If the user is registered they are shown the relevant dashboard (at this stage they can be blank with text on the page saying their role (i.e CHW, practitioner etc)
• If the user is not registered they are shown a blank page that says "not registered"

Technical Implementations/notes

• logging in should be provided using Web3Connect to enable any kind of wallet that the user has to intergrate
• to validate that a user has indeed logged in it should ask them to sign a message.
• redirect after use login should be done to the page of the user type which is retrieved from the smart contract

Supporting documents

@chrismaree please add screenshots

Format server time to SA time

right now the server time is GMT. should be SA time

Improve unit test coverage for smart contracts

Ad CI and test coverage to smart contracts for CircleCI

View wallet amount in card

For all user kinds one of the cards above the table should show their account balance. if you click this it should open your Sokol wallet.

Health Worker 'Home' tab Dashboard Styling: 1. Add Total registered for Month, Week & Total 2. Change token name from POA to Dai 3. Add Local currency token balance equivalent 4. Change default fields to: Patient, Practitioner, Interaction, Prescriptions, Date, Notes/Follow Up Action

Deploy current sprint 3 version to production

Superuser dashboard (views and donates)

Superuser dashboard (views and donates)

Once the superuser has connected to the dapp they see this dashboard

Acceptance criteria

• View all TX's that took funds out or put funds into the vault
• A button called "donate" that opens a model, the model has a text field for the amount the superuser wants to donate. There is a "Donate" button on the right and a "Cancel" button on the left. "Donate" will make a transaction to debit the superuser, cancel will cancel.
• Button to add a new admin to the system. Enable super user to add new admins

Technical details

@chrismaree

Supporting documents

@chrismaree

Super User & Health Worker 'Interaction' change to "PRESCRIPTION" tab styling: Change tab to PRESCRIPTION, add following field. (if possible, add notes field) Prescriptions, Prescription number. Remove Tokens sent field

Health Worker 'Practitioner' tab styling: 1. remove wallet addresses field. 2. Put Interaction field 3. Put Patient field 3. Include date for each interaction

Ratings logging for patient interactions

Use same categories as what was in the MVP. This should be done on the CHW's screen while recording an interaction. This requires part of the API to be changed as well as including this in the payout calculation.

Implement contract upgradability.

Openzeplin OS.

Dropdown colour issues

dropdown colours are wrong on modals. these should be a shade of grey and easier to read

Health Worker 'Patient' tab styling: 1. remove wallet addresses field. 2. Put Interaction field 3. Put Practitioner field 3. Include date for each interaction

Change "Record Interaction" dashboard layout from portrait to Landscape (front-end)

Enable the Ability to click on any system user and view a dashboard with a chronological history of their system activities

Front End refinements and bugs

• Router broke when not a direct re-route
• home page does not have text. says lorem ipsum. This needs to be changed.
• Modal close button all cases. Every model I can open should have a close button.
• When sign up happens on an existing user they should be re-directed to tair login page.
• Remove record activity for the patient page.
• Catch if the user is not on the right next work and re-direct them

Wallet address not recognised page

Wallet address not recognised page

This is the page a user gets directed to if they do not have an address that is registered on the contracts

Acceptance criteria

• There is a button in the middle of the page that says "Register with a CHW"
• If the user clicks this button a QR code is displayed on the screen. This QR code is their address in a QR code.
• They can then show this page to the login step

Sprint 1 Refiement

• - Add mobile number
• - Visual indication of authentication of the user. See if admin, CHW, patient or practitioner. This can go in the top right of the window.
• - Wiring of cards on home page for number of patients, practitioners CHW ect.
• - date of birth error when calling createNewUser

Text styling on dropdown menus is inconsistent

The text here should be the same as the text here

Superuser dashboard (actions and views)

Superuser (actions and views)

On the superuser dashboard after connecting with the app, the superuser can CRUD actions as well as view the balances.

Acceptance criteria

• View the funding the vault currently has
• Create actions (things a CHW can record, i.e patient interactions) and set the price of the action (in the ERC20 token being used (i.e DAI))
• Search pre-existing actions
• Change the price of searched actions, as well as delete.

Update readme and repo

Better structure of the repo, documentation

Outstanding issues for phase 3

• Add env file to the react app

• wait zero blocks. right now the front end waits a number of blocks before updating. this should happen instantly.

• payout function still gives RCP message error!!! this one is NBNB.

• only super admin should have donate button. right now it's shown on all users.

• Fix logo. this was not loading in production.

• Add "Ribbon Incentives Ecosystem App" text to "Insert client logo here"

• routing error on logout. If I click logout it did not route me to the login page.

Fix TX processing

Right now some transaction's have a tx gas limit. This should be removed on all calls. overall speed of the UI should be tested at all functionality

Router broke when not a direct re-route

If going from one page to another page the router brakes sometimes. This requires a history to be added to react.