Guardian

Overview

Guardian is a modular open-source solution that includes best-in-class identity management and decentralized ledger technology (DLT) libraries. At the heart of Guardian solution is a sophisticated Policy Workflow Engine (PWE) that enables applications to offer a digital (or digitized) Measurement, Reporting, and Verification requirements-based tokenization implementation.

HIP-19 · HIP-28 · HIP-29 · Report a Bug · Request a Policy or a Feature

Discovering Digital Environmental Assets assets on Hedera

As identified in Hedera Improvement Proposal 19 (HIP-19), each entity on the Hedera network may contain a specific identifier in the memo field for discoverability. Guardian demonstrates this when every Hedera Consensus Service transaction is logged to a Hedera Consensus Service (HCS) Topic. Observing the Hedera Consensus Service Topic, you can discover newly minted tokens.

In the memo field of each token mint transaction you will find a unique Hedera message timestamp. This message contains the url of the Verifiable Presentation (VP) associated with the token. The VP can serve as a starting point from which you can traverse the entire sequence of documents produced by Guardian policy workflow, which led to the creation of the token. This includes a digital Methodology (Policy) HCS Topic, an associated Registry HCS Topic for that Policy, and a Project HCS Topic.

Please see p.17 in the FAQ for more information. This is further defined in Hedera Improvement Proposal 28 (HIP-28).

Quickstart

This procedure is useful for demos, quick testing, and hackathons. It will only start the minimum required services for using the main Guardian features. It will not start features like the AI or MRV sender services, Prometheus integration, Grafana integration, etc.

1. Ensure to have Git and Docker installed on your machine.

2. Clone this repository

   git clone https://github.com/hashgraph/guardian.git
   cd guardian
   

3. Login or register on the Hedera Developer Portal.

4. Generate an ED25519 key pair and account.

5. Copy your AccountID (i.e, 0.0.123456...) and the associated DER Encoded Private Key (i.e., 302e020100300506032b657004220420....).

6. Create a local .env file in the root directory of your project and update it with your AccountID and private key.

   OPERATOR_ID=0.0.123456...
   OPERATOR_KEY=302e020100300506032b657004220420....
   

7. Start the environment with:

   docker compose -f docker-compose-quickstart.yml up --pull=always -d
   

8. Navigate to http://localhost:3000 in your web browser.

9. If you want to stop the environment, preserving all the local data, use:

   docker compose -f docker-compose-quickstart.yml stop
   

10. If you want to destroy the environment, loosing all the local data, use:

    docker compose -f docker-compose-quickstart.yml down
    

Getting started

To get a local copy up and running quickly, follow the steps below. Please refer to https://guardian.hedera.com for complete documentation.

Note. If you have already installed another version of Guardian, remember to perform a backup operation before upgrading.

Prerequisites

Software

1. Git – source-control tooling
2. Docker – one-command build & run (recommended)
3. MongoDB v6, Node.js v24.15+, and NATS 2.9.25 – auto-provisioned when using Docker Compose
4. IPFS storage (choose one):
   • Storacha account – IPFS pinning service (formerly Web3.Storage)
   • Filebase account – S3-compatible IPFS pinning
   • Local IPFS node (e.g., Kubo) – auto-provisioned when using Docker Compose
5. Valkey – in-memory cache & message broker (auto-provisioned by the Docker stack)

When building the reference implementation, you can manually build every component or run a single command with Docker.

Hedera network

| Component | Testnet (default) | Mainnet (production) | | -------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------- | | Account | Create via Hedera Developer Portal | Create via Hedera-enabled wallet (e.g.HashPack) | | Key type | ED25519 | ED25519 | | Network | testnet | mainnet |

Fees: Mainnet operations incur HBAR costs—fund your account before running Guardian.

Preparing a Mainnet Account & Keys

1. Install a Hedera-enabled wallet (e.g., HashPack).

2. Create a Mainnet account and note the Account ID (0.0.x).

3. Export the ED25519 key pair

   • HashPack path: Settings → Manage Accounts → Export Private Key (DER format).

4. Update your .env

   HEDERA_NET=mainnet
   OPERATOR_ID=0.0.123456...
   OPERATOR_KEY=302e020100300506032b657004220420....
   

Preparing a Testnet Account & Keys

1. Create a Testnet account via the Hedera Developer Portal.

2. Record your Account ID (0.0.x).

3. Download the ED25519 private key (ignore ECDSA)

   • Select the DER Encoded Private Key — do not choose HEX Encoded.

4. Update your .env

   HEDERA_NET=testnet
   OPERATOR_ID=0.0.123456...
   OPERATOR_KEY=302e020100300506032b657004220420....
   

Automatic installation

Prerequisites for automatic installation

• Docker

If you build with docker MongoDB V6, Node.js v24.15+, Yarn and Nats 2.9.25 will be installed and configured automatically.

Installation

The following steps need to be executed in order to start Guardian using docker:

1. Clone the repo
2. Configure project level .env file
3. Update Hedera access variables
4. Setup IPFS
5. Build and launch with Docker
6. Browse to http://localhost:3000
7. For increased security remove credentials from .env file

Here the steps description follows:

1. Clone the repo

git clone https://github.com/hashgraph/guardian.git

2. Configure project level .env file

The main configuration file that needs to be provided to the Guardian system is the .env file. Note that these files contain sensitive configuration such as keys and access credentials which are only used at the initial start of Guardian. For increased security it is recommended to disable inbound network access until after the first run of Guardian, when the credentials configuration has been removed from .env file (see p8 below).

For this example purpose let's name the Guardian platform as "develop"

   GUARDIAN_ENV="develop"

NOTE: Every single service is provided in its folder with a .env.template file, this set of files are only needed for the case of Manual installation.

3. Update Hedera access variables

Update the following files with your Hedera Mainnet or Testnet account info (see prerequisites). Please check complete steps to generate Operator_ID and Operator_Key by looking at the link: How to Create Operator_ID and Operator_Key. The Operator_ID and Operator_Key and HEDERA_NET are all that Guardian needs to access the Hedera Blockchain assuming a role on it. This parameters needs to be configured in a file at the path ./configs, the file should use the following naming convention:

./configs/.env.\<GUARDIAN_ENV\>.guardian.system

There will be other steps in the Demo Usage Guide that will be required for the generation of Operator_ID and Operator_Key. It is important to mention that the Operator_ID and Operator_Key in the ./configs/.env.<GUARDIAN_ENV>.guardian.system will be used to generate demo accounts.

The parameter HEDERA_NET may assume the following values: mainnet, testnet, previewnet, localnode. choose the right value depending on your target Hedera network on which the OPERATOR_ID has been defined.

As examples:

following the previous example, the file to configure should be named: ./configs/.env.develop.guardian.system, this file is already provided in the folder as an example, only update the variables OPERATOR_ID, OPERATOR_KEY and HEDERA_NET.

OPERATOR_ID="..."
OPERATOR_KEY="..."
HEDERA_NET="..."

Starting from Multi-environment release (2.13.0) it has been introduced a new parameter PREUSED_HEDERA_NET. Multienvironemnt is a breaking ch