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:
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/
Learn about the latest improvements.
UNDP Carbon Registry is based on service oriented architecture (SOA). Following diagram visualize the basic components in the system.
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.
Serve all the system analytics. Generate all the statistics using the operational database. Horizontally scalable.
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)
.
System services can deploy in 2 ways.
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.
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.
Can add more options by implementing file handler interface
Change by environment variable FILE_SERVICE
. Supported types S3
, LOCAL(Default)
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?
Why Ledger Database?
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.
Carbon Registry contains 3 ledger tables.
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.
.
├── .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
IS_EMAIL_DISABLED
. When the emails are disabled email payload will be printed on the console. User account passwords needs to extract from this console log. Including root user account, search for a log line starting with Password (temporary)
on national container (docker logs -f undp-carbon-registry-national-1
). IS_EMAIL_DISABLED
=falseSOURCE_EMAIL
(Sender email address)SMTP_ENDPOINT
SMTP_USERNAME
SMTP_PASSWORD
DB_PASSWORD
env variable to change PostgresSQL database passwordROOT EMAIL
. If the email service is enabled, on the first docker start, this email address will receive a new email with the root user password.REACT_APP_MAP_TYPE
env variable to Mapbox
and add new env variable REACT_APP_MAPBOXGL_ACCESS_TOKEN
with MapBox public access token in web container. docker-compose up -d --build
. This will build and start containers for following services,
cd backend/service
yarn run sls:install
serverless invoke local --stage=local --function setup --data '{"rootEmail": "<Root user email>","systemCountryCode": "<System country Alpha 2 code>", "name": "<System country name>", "logoBase64": "<System country logo base64>"}'
sls offline --stage=local
http://localhost:3000/local/national
aws cloudformation deploy --template-file ./deployment/aws-formation.yml --stack-name carbon-registry-basic --parameter-overrides EnvironmentName=<stage> DBPassword=<password> --capabilities CAPABILITY_NAMED_IAM
aws lambda invoke \
--function-name carbon-registry-services-dev-setup --cli-binary-format raw-in-base64-out\
--payload '{"rootEmail": "<Root user email>","systemCountryCode": "<System country Alpha 2 code>", "name": "<System country name>", "logoBase64": "<System country logo base64>"}' \
response.json
Carbon credit calculation implemented in a separate node module. Please refer this for more information.
Serial Number generation implemented in a separate node module. Please refer this for more information.
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 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 |
data-importer
to docker-compose
file replicator
service RUN_MODULE
env variable with comma separated. docker-compose
file replicator
service.
System pre-defined user roles are as follows,
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 implemented using ReactJS framework. Please refer getting started with react app for more information.
For integration, reference RESTful Web API Documentation documentation via Swagger. To access
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.
For transparent uptime monitoring go to status.APP_URL Open source code available at https://github.com/undp/carbon-registry-status
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.