Shield

Project Shield is a POC volunteering app, matching located helpers/volunteers with nearby vulnerable users requiring assistance (for shopping requests). Users have funds from which they reward helpers for completing requests. Users and helpers have associated balances of funds, denominated in S (shield) tokens.

Slides (may not be publically accessible)

Screenshot

Supporting materials (may not be publically accessible)

Video (public)

Requirements

• DFX 0.5.8 (!)
• React and other javascript detritus.
• tested on Linux (script run.sh may need adapting to MacOS).

Guide to the code

The dfx project is a multi-canister project with 2 main canisters and 20 identical, replicated agent canisters used to simulate additional human users/helpers making/servicing requests.

• Shield canister: Centralized mutable registry of users, helpers and requests. The former are authenticated by caller id (for better or worse). Implemented using three base HashMaps.

• Shield front-end: react, multi-page (?) front-end displaying maps with pins for helpers and (nearby) requests. Appearance basic but fully functional, should be stylable via css (future work).

• Balance canister: central bank managing user accounts storing shield tokens. Authenticated by caller id (for better or worse). Endowed by shield canister, used both by users and helpers. Account creation and transfers initiated solely by shield canister (the trust principal, for want of a better name).

• User canister(s) Generic user agent capable of impersonating a single shield user or shield helper. Used by test script run.sh to prepopulate the replica with a small number of users and canisters. Forged to set up an artificial environment of users/helpers located around Zurich. Each agent canister registers itself with shield. Each user agent additionally makes a single request (for help purchasing some item).

TODOs:

• rename user canister to more generic agent canister (serving role of shield user or helper).
• user-specified rewards in UI (implemented, but not exposed, default to 1 shield token).
• HTML input-validation
• token exchange.
• privacy-oriented design (we record way to much but that was the spec).
• Escrow to avoid overspend by user (user can make more requests than he can afford)

Known bugs:

• default user/helper field values can't be changed in UI
• helper registration polls for request before registration, provoking a reject.

Getting the code

git clone git@github.com:crusso/shield.git
cd shield
npm install

Running

Start the replica

$ dfx start --background

Building

You must have started the replica first in order to for the build to obtain canister ids (see above).

$ dfx build
Building canisters...
Building frontend...
Bundling assets with canisters...

Test Script

Once build, you can execute this script.

$ ./run.sh

Runs a little test script that (re-)starts dfx, installs all canisters, and starts some agent canisters (10 distinct users and 10 distinct helpers).

Prints two URLs, one for the (generic) CanDid interface, the other for the custom frontend UI.

Output:

...
Frontend UI: http://localhost:8000/?canisterId=ic:0D0000000000000000000000000000000001D2

Open the shield frontend URL in a browser, and again in private browser window(s), in order to register users or helpers with different principals.

Manual installation (sans test script).

$ dfx canister install -all

Note that dfx reports several canister ids - you'll need to use the actuall ID (not the ondisplayed here) in the following URLs for the shield_assets canister.

Opening candid UI

E.g. (but using the actual canister ID returned on installation)

$ firefox http://localhost:8000/candid?canisterId=ic:0D0000000000000000000000000000000001D2

Opening canister frontend UI

E.g. (but using the actual canister ID returned on installation)

$ firefox http://localhost:8000/canisterId=ic:0D0000000000000000000000000000000001D2

Troubleshooting

If dfx or the replica goes south, try getting back to a good state by doing this:

dfx stop
rm -r -f .dfx
rm -r -r canisters

and restart

$ dfx start --background