undp / carbon-registry

National Carbon Credit Registry Digital Public Good (DPG) by Digital For Climate (D4C) collaboration. Code coordinated by ExO/CDO & BPPS/Climate.
GNU Affero General Public License v3.0
41 stars 33 forks source link
carbon-emissions climate digital-public-goods sustainable-development-goals

GitHub last commit Uptime GitHub Workflow Status (with branch) GitHub Workflow Status (with branch)

National Carbon Credit Registry

The National Carbon Registry enables carbon credit trading in order to reduce greenhouse gas emissions.

As an online database, the National Carbon Registry uses national and international standards for quantifying and verifying greenhouse gas emissions reductions by projects, tracking issued carbon credits and enabling credit transfers in an efficient and transparent manner. The Registry functions by receiving, processing, recording and storing data on mitigations projects, the issuance, holding, transfer, acquisition, cancellation, and retirement of emission reduction credits. This information is publicly accessible to increase public confidence in the emissions reduction agenda.

The National Carbon Registry enables carbon credit tracking transactions from mitigation activities, as the digital implementation of the Paris Agreement. Any country can customize and deploy a local version of the registry then connect it to other national & international registries, MRV systems, and more.

The system has 3 key features:

Index

Standards

This codebase aims to fullfill the digital public goods standard: https://digitalpublicgoods.net/standard/ It is built according to the Principles for Digital Development: https://digitalprinciples.org/

Changelog

Learn about the latest improvements.

System Architecture

UNDP Carbon Registry is based on service oriented architecture (SOA). Following diagram visualize the basic components in the system.

alt text

System Services

National Service

Authenticate, Validate and Accept user (Government, Project Developer/Certifier) API requests related to the following functionalities,

Service is horizontally scalable and state maintained in the following locations,

Uses the Carbon Credit Calculator and Serial Number Generator node modules to estimate the project carbon credit amount and issue a serial number. Uses Ledger interface to persist project and credit life cycles.

Analytics Service

Serve all the system analytics. Generate all the statistics using the operational database. Horizontally scalable.

Replicator Service

Asynchronously replicate ledger database events in to the operational database. During the replication process it injects additional information to the data for query purposes (Eg: Location information). Currently implemented for QLDB and PostgresSQL ledgers. By implementing replicator interface can support more ledger replicators. Replicator select based on the LEDGER_TYPE environment variable. Support types QLDB, PGSQL(Default).

Deployment

System services can deploy in 2 ways.

External Service Providers

All the external services access through a generic interface. It will decouple the system implementation from the external services and enable extendability to multiple services.

Geo Location Service

Currently implemented for 2 options.

  1. File based approach. User has to manually add the regions with the geo coordinates. Sample File. To apply new file changes, replicator service needs to restart.
  2. Mapbox. Dynamically query geo coordinates from the Mapbox API.

Can add more options by implementing location interface

Change by environment variable LOCATION_SERVICE. Supported types MAPBOX, FILE(Default)

File Service

Implemented 2 options for static file hosting.

  1. NestJS static file hosting using the local storage and container volumes.
  2. AWS S3 file storage.

Can add more options by implementing file handler interface

Change by environment variable FILE_SERVICE. Supported types S3, LOCAL(Default)

Database Architecture

Primary/secondary database architecture used to store carbon project and account balances. Ledger database is the primary database. Add/update projects and update account balances in a single transaction. Currently implemented only for AWS QLDB

Operational Database is the secondary database. Eventually replicated to this from primary database via data stream. Implemented based on PostgresSQL

Why Two Database Approach?

  1. Cost and Query capabilities - Ledger database (blockchain) read capabilities can be limited and costly. To support rich statistics and minimize the cost, data is replicated in to a cheap query database.
  2. Disaster recovery
  3. Scalability - Primary/secondary database architecture is scalable since additional secondary databases can be added as needed to handle more read operations.

Why Ledger Database?

  1. Immutable and Transparent - Track and maintain a sequenced history of every carbon project and credit change.
  2. Data Integrity (Cryptographic verification by third party).
  3. Reconcile carbon credits and company account balance.

Ledger Database Interface

This enables the capability to add any blockchain or ledger database support to the carbon registry without functionality module changes. Currently implemented for PostgresSQL and AWS QLDB.

PostgresSQL Ledger Implementation storage all the carbon project and credit events in a separate event database with the sequence number. Support all the ledger functionalities except immutability.

Single database approach used for user and company management.

Ledger Layout

Carbon Registry contains 3 ledger tables.

  1. Project ledger - Contains all the project and credit transactions.
  2. Company Account Ledger (Credit) - Contains company accounts credit transactions.
  3. Country Account Ledger (Credit) - Contains country credit transactions.

The below diagram demonstrates the the ledger behavior of project create, authorise, issue and transfer processes. Blue color document icon denotes a single data block in a ledger.

alt text

Authentication

Project Structure

.
├── .github                         # CI/CD [Github Actions files]
├── deployment                      # Declarative configuration files for initial resource creation and setup [AWS Cloudformation]
├── backend                         # System service implementation
    ├── services                    # Services implementation [NestJS application]
        ├── src
            ├── national-api        # National API [NestJS module]      
            ├── stats-api           # Statistics API [NestJS module]
            ├── ledger-replicator   # Blockchain Database data replicator [QLDB to Postgres]
            ├── shared              # Shared resources [NestJS module]     
        ├── serverless.yml          # Service deployment scripts [Serverless + AWS Lambda]
├── libs
    ├── carbon-credit-calculator    # Implementation for the Carbon credit calculation library [Node module + Typescript]
    ├── serial-number-gen           # Implementation for the carbon project serial number calculation [Node module + Typescript]
├── web                             # System web frontend implementation [ReactJS]
├── .gitignore
├── docker-compose.yml              # Docker container definitions
└── README.md

Run Services As Containers

Run Services Locally

Deploy System on the AWS Cloud

Carbon Credit Calculator

Carbon credit calculation implemented in a separate node module. Please refer this for more information.

Serial Number Generation

Serial Number generation implemented in a separate node module. Please refer this for more information.

External Connectivity

ITMO Platform

  1. Carbon Registry make a daily to the retrieve ITMO platform projects.
  2. Projects create in the Carbon Registry when projects are authorized in the ITMO Platform
  3. The Carbon Registry update when the projects are Issued with credits in the ITMO Platform

Lifecycle

alt text

Project Creation and Authorisation

Credit Issuance

Field Mapping

Company Name in the Carbon Registry Mandatory in the Carbon Registry Name in the ITMO Platform
Tax ID (taxId) Yes company
Name (name) Yes company
Email (email) Yes Set default : nce.digital+[organisation]@undp.org
Phone Number (phoneNo) Yes Set default : 00
Website
Address Set default : Country if the Registry
Logo
Country (country) Set default : Country of the Registry
Role (companyRole) Yes Set default : ProgrammeDeveloper

User
Name in the Carbon Registry Mandatory in the Carbon Registry Name in the ITMO Platform
Email (email) Yes Set default : nce.digital+[organisation]@undp.org
Role (role) Yes Set default : Admin
Phone Number (phoneNo) Set default : 00

Project
Name in the Carbon Registry Mandatory in the Carbon Registry Name in the ITMO Platform
Project Name (title) Yes Name
External ID (externalId) Yes id
Credit Issuance Serial Number
Current Status Set default : Pending
Applicant Type Set default : Project Developer
Sector (sector) Yes Sector
Sectoral Scope (sectoralScope) Yes Sector
Project Start Date (startTime) Yes createdAt
Project End Date (endTime) Yes createdAt + 10 years
Geographical Location (Regional) (geographicalLocation) Yes country (Name not mentioned as ISO3 or actual name)
Buyer Country Eligibility
Project Cost (USD) (programmeCostUSD) Yes Set default : Null
Financing Type
Grant Equivalent Amount
Carbon Price (Dollars per ton)
Company company
Company Tax ID (proponentTaxVatId) Yes company
Company Percentage (proponentPercentage) Yes Set default : 100%
Type of Mitigation Action/Activity (typeOfMitigation) Yes Sector
GHGs Covered (greenHouseGasses) Yes Set default : CO2
Credits Authorised Set default : 100
Credits Issued Set default : 10
Credits Transferred
Credits Frozen
Credits Retired
Credits authorised for international transfer and use (Total cumulative maximum amount of Mitigation Outcomes for which international transfer and use is authorized)
Crediting Period (years)
Project Materials Files *
Project Materials Files *
Credit Calculation Fields / Mitigation Type Calculation
Agriculture
Land Area
Land Area Unit
Solar
energy generation
energy generation unit
consumer group

ITMO Sector Mapping

ITMO Sector Field Value Sector Sectoral Scope Type Of Mitigation
energy-distribution Energy Energy Distribution Energy Distribution
agriculture Agriculture Agriculture Agriculture
energy-industries Energy Energy Industry EE Industry
Default Other Energy Industry EE Industry

Assumptions

Docker Integration Setup

  1. Append data-importer to docker-compose file replicator service RUN_MODULE env variable with comma separated.
  2. Update following env variables in the docker-compose file replicator service.
    • ITMO_API_KEY
    • ITMO_EMAIL
    • ITMO_PASSWORD
    • ITMO_ENDPOINT
  3. Projects will import on each docker restart.

User Onboarding and Permissions Model

User Roles

System pre-defined user roles are as follows,

User Onboarding Process

  1. After the system setup, the system have a Root User for the setup email (one Root User for the system)
  2. Root User is responsible for creating the Government entity and the Admin of the Government
  3. The Government Admin is responsible for creating the other companies and Admins of each company.
  4. Admin of the company has the authority to add the remaining users (Admin, Managers, View Only Users) to the company.
  5. When a user is added to the system, a confirmation email should be sent to users including the login password.

User Management

All the CRUD operations can be performed as per the following table,

Company Role New User Role Authorized User Roles (Company)
Government Root Cannot create new one other than the default system user and Can manage all the users in the system
Government Admin
Manager
View Only
Root
Admin(Government)
All other Company Roles Admin
Manager
View Only
Root
Admin(Government)
Admin(Company)

Web Frontend

Web frontend implemented using ReactJS framework. Please refer getting started with react app for more information.

Localization

Application Programming Interface (API)

For integration, reference RESTful Web API Documentation documentation via Swagger. To access

Resource Requirements

Resource Minimum Recommended
Memory 4 GB 8 GB
CPU 4 Cores 4 Cores
Storage 20 GB 50 GB
OS Linux
Windows Server 2016 and later versions.

Note: Above resource requirement mentioned for a single instance from each microservice.

Status Page

For transparent uptime monitoring go to status.APP_URL Open source code available at https://github.com/undp/carbon-registry-status

Governance and Support

The United Nations Development Program (UNDP) is responsible for managing the application. To ensure alignment with international demand, Digital For Climate (D4C) will act as an advisory body to the Digital Public Good Carbon Registry codebase. D4C is a collaboration between European Bank for Reconstruction and Development (EBRD), United Nations Development Program (UNDP), United Nations Framework Convention on Climate Change (UNFCCC), International Emissions Trading Association (IETA), European Space Agency (ESA), and World Bank Group  that aims to coordinate respective workflows and create a modular and interoperable end-to-end digital ecosystem for the carbon market. The overarching goal is to support a transparent, high integrity global carbon market that can channel capital for impactful climate action and low-carbon development.

This code is managed by United Nations Development Programme as custodian, detailed in the press release. For technical questions, please visit the community of practice ‘Keeping Track of the Paris Agreement’ or submit through the open forum. For any other questions, contact us at digital4planet@undp.org.