The Guardian is a modular open-source solution that includes best-in-class identity management and decentralized ledger technology (DLT) libraries. At the heart of the Guardian solution is a sophisticated Policy Workflow Engine (PWE) that enables the ability for applications to offer a requirements-based tokenization implementation.
HIP-19
·
HIP-28
·
HIP-29
·
Report Bug
·
Request Policy or Feature
Table of Contents
As identified in Hedera Improvement Proposal 19 (hip-19), each transcaction on the Hedera network must contain a specific identifier in the memo field for discoverability. This is demonstrated in the Guardian when every Hedera Consensus Service transaction is logged to a Hedera Consensus Service Topic. Observing the Hedera Consensus Service Topic you can discover newly minted tokens. In the memo field of newley minted tokens, you will find a Verifiable Link which will allow users to discover the published standard the token is following and the entire history of the ESG asset and corresponding data to be publicy discoverable. This is futher defined in Hedera Improvement Proposal 28 (hip-28)
To get a local copy up and running follow these simple example steps. When building the reference implementation you can either manually build every componant or simply run one command with Docker.
- Docker (To build with one command)
- MongoDB and NodeJS (If you would like to manually build every componant)
- Hedera Testnet Account
-
Clone the repo
git clone https://github.com/hashgraph/guardian.git -
Update the following files with your Hedera Testnet account info as indicated. For example:
- in
ui-service/.env:
ACCOUNT_ID=0.0.123456789 PRIVATE_KEY=302e020100300506032b657004220420f4361ec73dc43e568f1620a7b7ecb7330790b8a1c7620f1ce353aa1de4f0eaa6 TOPIC_ID=0.0.28583- in
ui-service/.env.docker:
ACCOUNT_ID=0.0.123456789 PRIVATE_KEY=302e020100300506032b657004220420f4361ec73dc43e568f1620a7b7ecb7330790b8a1c7620f1ce353aa1de4f0eaa6 TOPIC_ID=0.0.28583- in
guardian-service/config.json:
{"OPERATOR_ID":"0.0.123456789","OPERATOR_KEY":"302e020100300506032b657004220420f4361ec73dc43e568f1620a7b7ecb7330790b8a1c7620f1ce353aa1de4f0eaa6"}The
TOPIC_IDis used when connecting to an existing topic. If you don't have one, just delete theTOPIC_IDline. - in
-
If you want to build with Docker (Once this step you are finished)
docker-compose up -d --build -
If you want to manually build every componant then build and run the services in the following sequence: Message Broker, UI Service, Guardian Service, and lastly the MRV Sender Service. See below for commands.
From the Message broker folder (Need to run first)
To build the service
npm install npm run buildTo start the service
npm startFrom the UI Service folder
To build the service
npm install npm run buildTo start the service (found on http://localhost:3002)
npm startFrom the Guardian Service folder
To build the service
npm install npm run buildTo start the service (found on http://localhost:3004)
npm startFrom the MRV Sender Service folder
To build the service
npm install npm run buildTo start the service (found on http://localhost:3005)
npm start
Place holder for some Executive Summary about the iRec Demo
-
The Guardian referance implementation comes with 3 predefined users:
- Root Authority: A standard registry, or a Root Authority in our scenario, is an organization that establishes science-based standards for measuring, reporting, and verifying (MRV) ecological benefit claims and issues value in the form of credit for claims that meet the standard set. A standard registry also authorizes validation and verification bodies (VVBs) to collect and process claims based on the established standard. The creation of scientific-based standards for MRV is a rigorous discipline that requires independence from commercial influence in the pursuit of accurate accounting of benefit or emissions claims. A standard registry organization can also maintain a central registry of credits they have issued that can be sold directly via the registry itself, or established as reference value on networks, exchanges, or marketplaces.
- Installer: In our scenario it can be either the project owner or developer. This is the entity (person or company) that owns the project whose activities will be the source of benefit claims in a process generically called measurement or monitoring, reporting and verification (MRV) to create a credit.
- Auditor: This is a 3rd part who will need to view/audit the entire chain of events; from establishment of the science-based standards through creation of the credit.
-
After running the installation commands, open a tab on your browser and navigate to http://localhost:3002/. Typically the way we start the reference implementation demonstration is by logging in as the Root Authority. Click the Demo Admin Panel drop down located in the upper right hand corner of the log in screen and select the Root Authority user.
-
You'll now be prompted to configure your Root Authority account. Press the Generate button to generate a Hedera Operator ID along with an Operator Key and also enter the name of your Root Authority. Press OK when finished. This will now create Hedera Consensus Service Topics, fill the account with test hBar, create a DID document, create a Verifiable Crendential, etc.
-
Next we move over to the Schemas tab. Some schemas are populated during the build of the solution. These schemas are the structure of which Verifiable Credentials will be filled out. You can click on the document link on the right hand side and notice fields that correlate to business requirements. Remember the iRec policy we mentioned at the beginning of the section? We will be creating the first step of that policy; which is to create an iRec registration applicant form. The current version of the solution allows you to either build schemas from scratch or import schemas. Navigate to the /Demo Artifacts/ folder and download the iRec_Application_Details.json file.
-
The next step of the flow is to create a token. Click the Tokens tab and click on Create Token. Here we can fillout the neccessary token information and token parameters such as Fungible/Non-Fungible, Freeze, KYC, etc. For purposes of this demo let us keep everything selected. When you click "OK" this action triggers Hedera Token Service to create the token on Hedera's testnet. Clicking on the "Token ID" will bring you to the Dragon Glass Hedera testnet explorer to track all token activity.
-
This could be one of the most interesting parts of the reference implementation. Now we will be creating the policy. In our case we will mimick the iRec policy. Click Create Policy and fill out the dialog box. Once the policy is complete we have just created our first Policy Workflow and Policy Action Execution instance!
-
On the right hand side of the Policies tab click the Edit button. This will open the Guardian's policy workflow editor. As described in the Hedera Improvement Proposal 28 (HIP-28) a Policy Workflow contains:
- Policy Workflow Workgroups
- Policy Workflow Actions
- Policy Workflow State Objects
- Policy Workflow State Transactions
The quickest way to go through this flow while learning how to configure a Policy Workflow is to import the configPolicy.ts file. To do so, navigate to the /Demo Artifacts/ folder and copy everything inside the irec-policy-config.txt file. Go back into the policy editor and click on the "code" icon in the upper right hand side. Paste the mock configuration and then click on the "block" icon that is just to the right of the "code" icon. You'll notice that the policy configuration editor now visually shows the Policy Workflow with all of the neccessary Workgroups, Actions, State Objects, and Transactions. Click through on several blocks and you'll notice that you can edit some elements on the right hand side. Depending on what you are clicking on different properties will display on the right bottom box. You can edit a number of different properites from permissions, dependencies, tags, UI elements, etc. Moving along with our flow, we will now press the Save button and then the Publish button.
-
Click on the Root Authority's profile icon and select "Log Out." We will now go back into the Admin Panel. This time we will select Installer
-
When signing into the Installer profile you will need to follow similar configuration steps as the Root Authority. After generatoring the Hedera Operating ID and Key the Installer profile will be configured, test hBar will be credited to the account, and a DID will be created.
-
Next, navigate to the Token tab and click the link icon to associate the Installer to the token we created as the Root Authority.
-
Now, we can click on the Policies tab. This is where the specific actions required by the Policy Workflow will be found. We can click the Open button to the right of the iRec policy the Root Authority created. Here we will see the form that is based on the imported schema in step 4. This form, is one of the Policy Workflow State Objects. Once you fill out the required information, press the OK button. Note: You'll see the progress bar spin right now. That's on purpose.
-
The next step of our flow is to log out and sign back in as the Root Authority. Navigate to the Policies tab and click the Open button on the far right. Here you will find the approval actions based on our Policy Workflow required by the Root Authority. You will be able to view the Verifiable Credential prior to approval by selecting the View Document link. Once you are ready to approve the document, you can click on the Approve button.
-
Navigate to the Tokens tab and click on the blue people icon on the far right. This view shows the Root Authority all of the users who have been associated to the tokens the Root Authority created. We will now click the Grant KYC button. We can now log out of the Root Authority account and back in as the Installer.
-
Navigate to the Policies tab and click the Open button on the far right. After the installer submited the form, the next Policy Workflow Action required by the Installer is to register their sensors. Click the Create Sensors and fill out the required information in the dialog box and select OK.
-
You'll notice that you just created a sensor and that sensor has been assigned a Decentralized Identifier and a Verifiable Credential. Click the Configuration button. This will begin the download of the Sensor configuraiton file. Save that in a handy place, because in a moment we will come back to it.
-
Open another tab on your browser and enter http://localhost:3005/. We now see our IoT simulator. You can either drag and drop the sensor configuration file to the big + in the upper left or you can click on that button to browser your computer. For simplicity sake, just click button next to Random Value for the IoT simulat to generate random Measurement, Reporting, and Validation (MRV) data. Click OK and press the green triangle to begin generating the data. Navigate back to Guardian Policies tab and you can click into the MRV tab. Here you will be able to view the data that the IoT sensor generated such as date, period, amount, etc.
-
The last step is to log out of the Installer account and log into the Auditor account. There are two tabs in this view: Audit and Trust Chain. Clicking into the Audit tab offers highlevel public information from our reference implementation such as the Verifiable Presentation ID, the Hash of the Verifiable Presentation, the DID of the sensor, the date information the Verifiable Presentation was created, the type of activity, and the ability to view the Verifiable Presentation.
-
Lastly, lets navigate to The Trust Chain tab. The Trust Chain tab will ask for one of two pieces of information, either the Verifiable Presentation ID (which can be found either in the Audit tab or in the memo field of the transaction field on a Hedera explorer like Dragon Glass) or the Transaction Hash. Entering either of those important identifers will open all nessessary information for you to discover. Important elements of that can be publicly discovered include token information, policy information, and all of the important information regarding the collection of Verifiable Credentials that make up the Verifiable Presentation.
We welcome all methodologies and workflow to be contributed to this repo as an open-source token template and Policy Workflow & Policy Action Execution instance. To do so, please follow the CONTRIBUTING.md instructions to submit a pull request.
This is critical to scaling the Hedera Sustainability Ecosystem.
This repo contains a reference implementation of the Guardian to learn how to use the componants for various applications. This reference implementation is designed with modularity so that different components may be swapped out based on various implementation requirements. Please see the Guardian's architecture diagram below:
The Guardian solution is built with the following major frameworks/libraries.
- NodeJS
- MongoDB
- Express
- FastMQ
- TypeORM
- Hedera-DID-JS-SDK
- W3C VC-JS-HTTP
- Angular
- crypto-browserify
Roadmap TBA
- [] Feature 1
- [] Nested Feature
See the open issues for a full list of proposed features (and known issues).
All notable changes to this project will be documented in this CHANGELOG.md file.
Thank you for your interest in contributing to the Guardian!
We appreciate your interest in helping us and the rest of our community. We welcome bug reports, feature requests, and code contributions.
For contributing guidlines please see the CONTRIBUTING.md here
This repo is under Apache 2.0 License. See LICENSE for more information.
Please do not file a public ticket mentioning the vulnerability. Refer to the security policy defined in the SECURITY.md.
For any questions please reach out to the Envision Blockchain Solutions team at:
- Website: <www.envisionblockchain.com>
- Email: info@envisionblockchain.com