Working with Protocol using Aries

Welcome to Protocol! This top-level repo was designed to help developers launch the full Kiva Protocol system locally on their machines. After all, who doesn't love a good demo?

Kiva Protocol uses Hyperledger Aries - if you haven't heard of it, or just want a refresher, feel free to check out the Aries Cloud Agent Python (ACA-Py) demo for an idea of what is possible with this tech.

Table of Contents

• Scripted Setup
• Simple Demo
• Full Stack Demo

Before You Start

You will need to install a few things on your machine before you can run this code package on your own. Here's the list along with suggested version numbers. You do you. :)

• git (2.24)
• Docker (20.10)
• docker-compose (1.27)
• Node.js (14.15)
  • You should also feel free to use nvm for added flexibility
• NPM (6.14)
• Java (11)

For Docker, we recommend increasing its allocated resources to:

• CPUs: 8
• Memory: 6 GB
• Swap: 2 GB

For Docker docs

Notes

We will be referencing the following GitHub repos several times. Though you should be able to install all the relevant code without them, here are the links:
protocol-demo
aries-guardianship-agency
aries-key-guardian
guardian-bio-auth
protocol-gateway
protocol-common (optional)
aries-controller (optional)

Scripted Setup

1. Create a protocol-all directory, and then move into the directory.

mkdir protocol-all
cd protocol-all

The idea here is that we want some top level folder on your machine that contains all our repos in one place

NOTE: Unless specified, always run commands from within the protocol-all directory

2. Clone all our repos using these commands (please note the commands assume you have ssl setup):

git clone https://github.com/kiva/protocol-demo
./protocol-demo/scripts/get_code.sh

3. Populate the .env files with some mock values

./protocol-demo/scripts/dummy_env.sh

4. Run NPM install within each repo. We've created a utility script to do this for you!

./protocol-demo/scripts/npm_setup.sh

Note: if this is your first time you'll need to manually pull the latest bcgov image:

docker pull bcgovimages/aries-cloudagent:py36-1.16-1_0.7.1

5. Build all of the docker containers

./protocol-demo/scripts/simple_build.sh

If you've tried this demo before, you may have older instances of the agents running. If you need to clean up your containers, you can run the following command. (This will delete ALL Docker container instances. You've been warned.)

docker ps -aq | xargs docker rm -f
docker network prune -f

Simple Demo

The simple demo includes the minimum pieces to spin up agents and run through the issuing and verifying flows with them. Please note that you MUST complete every step of the Scripted Setup section before you try this.

1. Now that all the various repos have been set up, go into the protocol-demo repo

cd protocol-demo

2. Start up the stack (and run setup scripts)

./scripts/simple_start.sh

3. Run tests

npm run test

4. Once you've finished, stop everything

./scripts/simple_stop.sh

Full Stack Demo

The full stack demo includes the Guardianship system which includes authentication methods like fingerprint scanning to control agents.

This requires some additional setup scripts.

1. First you need ensure you have java installed on your machine and then you can run the setup scripts. From the protocol-all directory run

./protocol-demo/scripts/java_setup.sh

2. You then need to build the full services

./protocol-demo/scripts/full_build.sh

3. Now go into the protocol-demo repo

cd protocol-demo

4. Start up the full stack (and runs setup scripts) - this may take awhile and a lot of computer resources

./scripts/full_start.sh

5. Run tests

npm run test

6. When down stop everything

./scripts/full_stop.sh

Integrating with SSIrius

Kiva has created another package called SSIrius, which is designed to be an easy-to-use, flexible UI for doing all sorts of SSI transactions.

Kiva has deployed a Guardianship Gateway for you to play with, but if you'd like to use your local build of the Protocol backend instead, that's absolutely an option.

Getting SSIrius

Check out the SSIrius repo, and then in protocol-all (or anywhere else - again, you do you :) ), run the following command.

git clone https://github.com/kiva/ssi-wizard-sdk.git

Refer to the SSIrius documentation for information on how to get started.

Replacing the URL

Once you have the protocol-demo scripts running, there will be a Gateway URL running on your local machine on port 8080.

In your checked out SSIrius repo, go ahead and replace any instances of https://sandbox-gateway.protocol-prod.kiva.org with http://localhost:8080.

ngrok

If you're not going to be trying out QR code scanning, you can skip this section. If you are, you'll need to install ngrok in order to support communication via the Cloud Mediator between the SSIrius UI and your Mobile Wallet.

Fortunately, ngrok is very cool and very easy to install (though you will need to sign up for a free account).

Once you're ready to roll with ngrok, run the following command.

./ngrok http 3010

Then, in the aries-guardianship-agency/dummy.env and protocol-demo/docker-compose.yml files, replace the PUBLIC_URL variable's value with the URL generated by ngrok.

Unfortunately, once you've done this you'll need to run through the setup steps again, but we promise it's much quicker the second time around.