PERL.eco Carbon & Bio Asset Registry enables carbon credit trading in order to reduce greenhouse gas emissions and supports natural capital accounting to better value bio diverse ecosystems.
As an online database, PERL.eco Carbon & Bio Asset Registry uses national and international standards for quantifying and verifying greenhouse gas emissions reductions by programmes, 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. The Registry also stores information relevant to national bio asset inventories and enables governments to ensure equitable sharing of value from natural assets through bio genomics and other benefits within the economy. This information is publicly accessible to increase public confidence in the emissions reduction agenda.
PERL.eco Carbon & Bio Asset Registry enables carbon credit tracking transactions from mitigation activities, as the digital implementation of the Paris Agreement. Any country deploy a local version of the PERL.eco Registry then connect it to other national & international registries, MRV systems, and more.
The system has 3 key features:
- Analytics Dashboard: Enabling governments, companies, and certification bodies to operate transparently and function on an immutable blockchain.
- Carbon Credit Calculator: Standardized system According to the UNFCCC - CDM (Clean Development Mechanism) methodologies, across defined sectors.
- Serial Number Generator: Standardizing the technical format to allow for easy cross-border collaboration between carbon trading systems.
- About
- Standards
- Architecture
- Project Structure
- Run as Containers
- Run Services Locally
- Run Services on Cloud
- User Onboarding
- Web Frontend
- Localization
- API
- Status Page
- Governance & Support
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/
PERL.eco Carbon & Bio Asset Registry is built on the UNDP Carbon Registry which is based on service oriented architecture (SOA). Following diagram visualize the basic components in the system.
Authenticate, Validate and Accept user (Government, Programme Developer/Certifier) API requests related to the following functionalities,
- User and company CRUD operations.
- User authentication.
- Programme life cycle management.
- Credit life cycle management.
Service is horizontally scalable and state maintained in the following locations,
- File storage.
- Operational Database.
- PERL.eco Ledger Database.
Uses the Carbon Credit Calculator and Serial Number Generator node modules to estimate the programme carbon credit amount and issue a serial number. Uses Ledger interface to persist programme 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 PERL.eco Ledger and Operational Query Database. By implementing replicator interface can support more ledger replicators.
Replicator select based on the LEDGER_TYPE environment variable. Support types PERL, OQDB(Default).
System services can deploy in 2 ways.
- As a Container - Each service boundary containerized in to a docker container and can deploy on any container orchestration service. Please refer Docker Compose file
- As a Function - Each service boundary packaged as a function (Serverless) and host on any Function As A Service (FaaS) stack. Please refer Serverless configuration file
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.
- 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.
- 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.
- NestJS static file hosting using the local storage and container volumes.
- AWS S3 file storage.
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 programme and account balances. Ledger database is the primary database. Add/update programmes and update account balances in a single transaction. Currently implemented only for PERL.eco Ledger
Operational Database is the secondary database.
Why Two Database Approach?
- 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.
- Disaster recovery
- Scalability - Primary/secondary database architecture is scalable since additional secondary databases can be added as needed to handle more read operations.
Why Ledger Database?
- Immutable and Transparent - Track and maintain a sequenced history of every carbon programme and credit change.
- Data Integrity (Cryptographic verification by third party).
- Reconcile carbon credits and company account balance.
Ledger Database Interface
This enables the capability to interface with the PERL.eco Ledger database. Single database approach used for user and company management.
Carbon Registry contains 3 ledger tables.
- Programme ledger - Contains all the programme and credit transactions.
- Company Account Ledger (Credit) - Contains company accounts credit transactions.
- Country Account Ledger (Credit) - Contains country credit transactions.
The below diagram demonstrates the the ledger behavior of programme create, authorise, issue and transfer processes. Blue color document icon denotes a single data block in a ledger.
- JWT Authentication - All endpoints based on role permissions.
- API Key Authentication - MRV System connectivity.
.
├── .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 programme serial number calculation [Node module + Typescript]
├── web # System web frontend implementation [ReactJS]
├── .gitignore
├── docker-compose.yml # Docker container definitions
└── README.md
- Update docker compose file env variables as required.
- Currently all the emails are disabled using env variable
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 withPassword (temporary)on national container (docker logs -f undp-carbon-registry-national-1). - Add / update following environment variables to enable email functionality.
IS_EMAIL_DISABLED=falseSOURCE_EMAIL(Sender email address)SMTP_ENDPOINTSMTP_USERNAMESMTP_PASSWORD
- Use
DB_PASSWORDenv variable to change Operational Database database password - Configure system root account email by updating environment variable
ROOT 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. - By default frontend does not show map images on dashboard and programme view. To enable them please update
REACT_APP_MAP_TYPEenv variable toMapboxand add new env variableREACT_APP_MAPBOXGL_ACCESS_TOKENwith MapBox public access token in web container.
- Currently all the emails are disabled using env variable
- Add user data
- Update organisations.csv file to add organisations.
- Update users.csv file to add users.
- When updating files keep the header and replace existing dummy data with your data.
- These users and companys add to the system each docker restart.
- Run
docker-compose up -d --build. This will build and start containers for following services,- PostgresDB container
- National service
- Analytics service
- Replicator service
- React web server with Nginx.
- Web frontend on http://localhost:3030/
- API Endpoints,
- Setup Operational Database locally and create a new database.
- Update following DB configurations in the .env.local file (If the file does not exist please create a new .env.local)
- DB_HOST (Default localhost)
- DB_PORT (Default 5432)
- DB_USER (Default root)
- DB_PASSWORD
- DB_NAME (Default carbondbdev)
- Move to folder
cd backend/service - Run
yarn run sls:install - Initial user data setup
serverless invoke local --stage=local --function setup --data '{"rootEmail": "<Root user email>","systemCountry": "<System country Alpha 2 code>", "name": "<System country name>", "logoBase64": "<System country logo base64>"}' - Start all the services by executing
sls offline --stage=local - Now all the system services are up and running. Swagger documentation will be available on
http://localhost:3000/local/national
- Execute to create all the required resources on the AWS.
aws cloudformation deploy --template-file ./deployment/aws-formation.yml --stack-name carbon-registry-basic --parameter-overrides EnvironmentName=<stage> DBPassword=<password> --capabilities CAPABILITY_NAMED_IAM - Setup following Github Secrets to enable CI/CD
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- Run it manually to deploy all the lambda services immediately. It will create 2 lambda layers and following lambda functions,
- national-api: Handle all carbon registry user and program creation. Trigger by external http request.
- replicator: Replicate Ledger database entries in to Operational Database for analytics. Trigger by new record on the Kinesis stream.
- setup: Function to add initial system user data.
- Create initial user data in the system by invoking setup lambda function by executing
aws lambda invoke \ --function-name carbon-registry-services-dev-setup --cli-binary-format raw-in-base64-out\ --payload '{"rootEmail": "<Root user email>","systemCountry": "<System country Alpha 2 code>", "name": "<System country name>", "logoBase64": "<System country logo base64>"}' \ response.json
- Carbon Registry make a daily to the retrieve ITMO platform programmes.
- Programmes create in the Carbon Registry when programmes are authorized in the ITMO Platform
- The Carbon Registry update when the programmes are Issued with credits in the ITMO Platform
- Authorisation of programmes in the ITMO Platform identified by the event name: "ITMO-Design Document (DD) & Validation Report / Upload on National Public Registry".
- If the Company Tax Id doesn’t exist in the Carbon Registry, that company created in the Carbon Registry.
- When creating the programme:
- The programme created with the state “Pending”
- The credit estimate set to 100 by default
- The company percentage set to 100%
- The serial number for the programme generated the same as any other programme in the Carbon Registry.
- Programmes retrieved from the ITMO Platform and created in the Carbon Registry can Authorised/Rejected by a Government user the same as any other programme in the Carbon Registry
- When a programme is authorised, the authorised credits will be the default credit estimate mentioned above. The programme can be issued with credits by a Government user the same as any other programme in the Carbon Registry.
- Credits can be issued for programmes retrieved from the ITMO Platform and created in the Carbon Registry in two ways;
- By a Government user the same as any other programme.
- Credit issuance in the ITMO Platform which should be reflected in the Carbon Registry.
- In the case of 2 above,
- Credit issuance identified by the event name: "Upload Final Monitoring Report" in the ITMO Platform.
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 |
Programme
| Name in the Carbon Registry | Mandatory in the Carbon Registry | Name in the ITMO Platform |
|---|---|---|
| Programme Name (title) | Yes | Name |
| External ID (externalId) | Yes | id |
| Credit Issuance Serial Number | ||
| Current Status | Set default : Pending | |
| Applicant Type | Set default : Programme Developer | |
| Sector (sector) | Yes | Sector |
| Sectoral Scope (sectoralScope) | Yes | Sector |
| Programme Start Date (startTime) | Yes | createdAt |
| Programme End Date (endTime) | Yes | createdAt + 10 years |
| Geographical Location (Regional) (geographicalLocation) | Yes | country (Name not mentioned as ISO3 or actual name) |
| Buyer Country Eligibility | ||
| Programme 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) | ||
| Programme 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 |
- Programme estimated credit amount is 100.
- Programme issued credit amount is always 10.
- Append
data-importertodocker-composefilereplicatorserviceRUN_MODULEenv variable with comma separated. - Update following env variables in the
docker-composefilereplicatorservice.- ITMO_API_KEY
- ITMO_EMAIL
- ITMO_PASSWORD
- ITMO_ENDPOINT
- Programmes will import on each docker restart.
System pre-defined user roles are as follows,
- Root
- Company Level (National Government, Programme and Certification Company come under this level)
- Admin
- Manager
- View Only
- After the system setup, the system have a Root User for the setup email (one Root User for the system)
- Root User is responsible for creating the Government entity and the Admin of the Government
- The Government Admin is responsible for creating the other companies and Admins of each company.
- Admin of the company has the authority to add the remaining users (Admin, Managers, View Only Users) to the company.
- When a user is added to the system, a confirmation email should be sent to users including the login password.
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) |
- All users can edit own user account except Role and Email.
- Users are not allowed to delete the own account from the system.
Web frontend implemented using ReactJS framework. Please refer getting started with react app for more information.
- Languages (Current): English
- Languages (In Progress): French. Spanish For updating translations or adding new ones, reference https://github.com/perlin-network/carbon-registry/tree/main/web/public/Assets/i18n
For integration, reference RESTful Web API Documentation documentation via Swagger. To access
- National API: api.APP_URL/national
- Status API: api.APP_URL/stats
| 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/perlin-network/carbon-registry-status
Digital For Climate (D4C) is responsible for managing the application. D4C is a collaboration between the 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. For any questions, contact us at [email protected] .