OGCR help
Login

Tokens — How it works

Go to Chain

How OGCR's tokens work, from the OBP glossary. The glossary is generated from the smart contracts' own documentation, so it is always the authority on how the contracts behave.

OGCR Smart Contracts

The OGCR Smart Contracts are the Solidity contracts that hold the OGCR registry's tokens on the OGCR chain (chain id 20253). Each token attests to a record in the registry: it carries a snapshot of the record, a URL back to it and a hash of it, so anyone can check that the record has not changed since the token was minted.

The token family

ParcelNFT ──────────────┐
                        v
                   ActivityNFT <── CertificationNFT   (one per certificate; a
                        ^                              re-certification adds one)
                        │
            CarbonCreditBatchNFT ── owns ──> token-bound account (ERC-6551)
                                                   │ holds
                                                   v
                                             CarbonCredit (ERC-20)
Contract Standard Symbol One token per
ParcelNFT ERC-721 PARCEL parcel_id
ActivityNFT ERC-721 ACT activity_id
CertificationNFT ERC-721 CERT certificate_of_compliance_id
CarbonCreditBatchNFT ERC-721 + ERC-6551 CCB carbon_credit_batch_id
CarbonCredit ERC-20, 18 decimals CC (fungible)
CarbonERC6551Registry, CarbonERC6551Account ERC-6551 infrastructure for the batch accounts

ActivityNFT records the parcels linked to the activity (parcel_ids). CertificationNFT and CarbonCreditBatchNFT point at their activity's token (activity_nft_id). A re-certification is a new certificate_of_compliance record, so it mints a new CertificationNFT for the same activity.

What a token stores

Each token stores its record's fields on chain, and tokenURI returns them as ERC-721 metadata (data:application/json;base64,...), so no off-chain metadata server is needed.

Fields ending in _url or _uri link to the registry record on OBP-API. Fields ending in _hash are the keccak256 hash of the registry's response body for that record at mint time.

  • ParcelNFT: parcel_id, parcel_uri, parcel_hash.
  • ActivityNFT: activity_id, operator_id, operator_name, name, summary, website, activity_type, unit_types, city, country_id, certification_scheme_id, parcel_ids, start_date, end_date, activity_url, activity_hash.
  • CertificationNFT: the certificate of compliance, activity, certification scheme, certification body and audit report (each with id or name, URL and hash), country_id, issue_date, expiry_date, unit_types, certification_status, and the certified quantities: carbon_removals_under_baseline, soil_emissions_under_baseline, permanent_net_carbon_removal_benefit, carbon_farming_temporary_net_carbon_removal_benefit, carbon_farming_net_soil_emission_reduction_benefit, carbon_storage_temporary_net_carbon_removal_benefit. The quantities are decimal strings in tonnes CO2e, exactly as recorded on the certificate. An empty value means the certificate has none, and tokenURI leaves it out.
  • CarbonCreditBatchNFT: carbon_credit_batch_id, batch_name, unit_type, amount, monitoring_period_start_date, monitoring_period_end_date, status_code, issue_date, expiry_date, country_id, and the activity, operator, certificate of compliance, certification scheme and certification body it was issued under (each with URL and hash).

Token data is fixed by each contract's storage layout. Changing a token's fields means deploying a new contract; tokens minted on the old one stay there.

Carbon credit batches

A batch is the credits of one unit type issued for an activity over one monitoring period. A verified monitoring period produces one batch for each benefit field that has a value:

Benefit field on the verification batch_name unit_type
permanent_net_carbon_removal_benefit Permanent Removals Carbon Credit Batch Permanent Removal
carbon_farming_temporary_net_carbon_removal_benefit Carbon Farming Removals Carbon Credit Batch Carbon Farming Sequestration
carbon_farming_net_soil_emission_reduction_benefit Soil Emissions Reductions Carbon Credit Batch Soil Emission Reduction
carbon_storage_temporary_net_carbon_removal_benefit Carbon Storage in Product Carbon Credit Batch Carbon Storage in Product

When a batch is minted, it gets its own token-bound account (ERC-6551), and the batch's CarbonCredit units are minted into that account. One credit is one tonne CO2e: 6.5 tonnes is 6500000000000000000 base units.

  • The batch owns its credits. Only the current holder of the batch token can move credits out of its account, so selling the batch token hands over the credits with it.
  • amount is fixed at mint. It records what was issued. The live balance is CarbonCredit.balanceOf of the batch's account (tokenBoundAccount(tokenId)).
  • Credits taken out of a batch are pooled. In an ordinary wallet, credits from different batches are interchangeable and no longer traceable to a batch.

Who can do what

  • Minter: each contract has a single minter, the tokenizer's key. Only the minter can mint. It can burn CarbonCredit only from a holder who has approved it with ERC-20 approve, so it cannot take credits without consent.
  • Owner: each contract's owner can change the minter (setMinter). It cannot mint or move tokens.
  • Holders: tokens are minted to the operator's wallet and can be transferred like any ERC-721 or ERC-20 token.

Safe to repeat

Each contract allows one token per registry id: minting the same parcel_id, activity_id, certificate_of_compliance_id or carbon_credit_batch_id again is rejected. CarbonCredit.mintedTo(address) records the total ever minted to an address, and does not drop when credits are moved out. The tokenizer funds a batch against mintedTo, not the balance, so credits the owner has already moved out are never issued twice.

Looking up a token

Each NFT contract maps a registry id to its token id, returning 0 for an id that has not been minted:

  • ParcelNFT.tokenIdByParcelId(parcel_id)
  • ActivityNFT.tokenIdByActivityId(activity_id)
  • CertificationNFT.tokenIdByComplianceId(certificate_of_compliance_id)
  • CarbonCreditBatchNFT.tokenIdByBatchId(carbon_credit_batch_id)

The full record is returned by getParcel, getActivity, getCertification and getBatch, or as metadata by tokenURI. The OGCR Chain Cache mirrors every token into OBP (parcel_on_chain, activity_on_chain, ...), so they can also be read through the registry's APIs.

When each token is minted is decided by the tokenizer; see the "What the tokenizer mints, and when" table in OGCR Architecture.

Source: OGCR-Smart-Contracts

OGCR Architecture

The OGCR registry records carbon activities, parcels, verifications and certificates, and turns verified facts into tokens on the OGCR blockchain. A spreadsheet defines the registry's data model and access rules, which are served as secured APIs. The on-chain state is mirrored back into the registry, where it can be filtered and combined with off-chain data.

Design goals

  • REST API driven. Every registry operation is a REST call with OpenAPI documentation, and every app and service works through the same APIs.
  • AI enabled. The Opey Agent and the OBP-MCP server let AI agents read and act on the registry through the same APIs, limited by the same Roles as the user.
  • Agile data model definition and construction. The data model is defined in a spreadsheet and built as Dynamic Entities at runtime, with their endpoints, Roles and indexes. Changing it needs no code change or redeploy, and existing records are kept.
  • Open source. OBP-API, the OBP-MCP server, Opey and the OGCR repositories are open source (AGPL-3.0).
  • Open standards. OAuth2, OpenID Connect, OpenAPI, JSON, MCP, and EVM tokens (ERC-721, ERC-20, ERC-6551).
  • Decoupled apps. OGCR-App, the Operator Platform and the Certification Platform are separate apps that use the API and OIDC for authentication.
  • OAuth2 / OIDC. People log in with an OpenID Connect provider, and apps and services call the API with OAuth2 tokens.
  • RBAC. Each operation on each entity needs a Role, and people get Roles through Role Groups.
  • Platform Apps. Services that work without a person, such as the chain cache and OBP Senti, call the API as themselves, with Scopes granted to their Consumer. The tokenizer will move to Platform App mode too. See the "Platform Apps" Glossary Item.
  • Dockerised deployment. Each service is built as a Docker image and deployed on Kubernetes.

The big picture

 Schema definition spreadsheet    OGCR-App, OGCR Operator     Opey Agent, Claude Code
              │                 and Certification Platforms         |
              v                                |                    v
    OGCR-DynamicEntities                       |               OBP-MCP server
              │ entity definitions, Roles,     |                    |
              │ Role Groups, Dynamic Queries   | CRUD and queries over OAuth2 / OIDC
              v                                v                    v
 +------------------------------------------------------------------+
 │  OBP-API: Dynamic Entities, generated CRUD endpoints,            |
 │  OAuth2 / OIDC, RBAC, indexes, Dynamic Queries (ogcr Space)      |
 +------------------------------------------------------------------+
              ^                                     ^
              │ polls for verified records          | writes *_on_chain records
              │ (reads only)                        |
       ogcr-tokenizer --mints--> OGCR chain <--reads-- OGCR-Chain-Cache
                                (chain id 20253,
                                 OGCR-Smart-Contracts)

Arrows point from the caller to the service it calls.

The components

OBP-API: the single gateway to the registry. It stores the Dynamic Entities and generates their CRUD endpoints. Every call is authenticated with OAuth2 / OIDC and checked against Roles (RBAC), such as CanCreateDynamicEntityRecord_activity, which people get through Role Groups. Indexes and Dynamic Queries serve filtered and joined views, such as the public registry.

OGCR-DynamicEntities: scripts that apply the schema definition spreadsheet to OBP-API. They create the entities (fields, types, references, indexes), the Role Groups and the Dynamic Queries, and check that OBP matches the spreadsheet.

OGCR-Smart-Contracts: Solidity contracts for chain 20253. ParcelNFT, ActivityNFT and CertificationNFT (ERC-721) each carry a snapshot of the registry record they attest to, a URL back to it and a hash of it. Each CarbonCreditBatchNFT owns an ERC-6551 account holding its CarbonCredit (ERC-20) balance.

OGCR Smart Contracts

The OGCR Smart Contracts are the Solidity contracts that hold the OGCR registry's tokens on the OGCR chain (chain id 20253). Each token attests to a record in the registry: it carries a snapshot of the record, a URL back to it and a hash of it, so anyone can check that the record has not changed since the token was minted.

The token family

ParcelNFT ──────────────┐
                        v
                   ActivityNFT <── CertificationNFT   (one per certificate; a
                        ^                              re-certification adds one)
                        │
            CarbonCreditBatchNFT ── owns ──> token-bound account (ERC-6551)
                                                   │ holds
                                                   v
                                             CarbonCredit (ERC-20)
Contract Standard Symbol One token per
ParcelNFT ERC-721 PARCEL parcel_id
ActivityNFT ERC-721 ACT activity_id
CertificationNFT ERC-721 CERT certificate_of_compliance_id
CarbonCreditBatchNFT ERC-721 + ERC-6551 CCB carbon_credit_batch_id
CarbonCredit ERC-20, 18 decimals CC (fungible)
CarbonERC6551Registry, CarbonERC6551Account ERC-6551 infrastructure for the batch accounts

ActivityNFT records the parcels linked to the activity (parcel_ids). CertificationNFT and CarbonCreditBatchNFT point at their activity's token (activity_nft_id). A re-certification is a new certificate_of_compliance record, so it mints a new CertificationNFT for the same activity.

What a token stores

Each token stores its record's fields on chain, and tokenURI returns them as ERC-721 metadata (data:application/json;base64,...), so no off-chain metadata server is needed.

Fields ending in _url or _uri link to the registry record on OBP-API. Fields ending in _hash are the keccak256 hash of the registry's response body for that record at mint time.

  • ParcelNFT: parcel_id, parcel_uri, parcel_hash.
  • ActivityNFT: activity_id, operator_id, operator_name, name, summary, website, activity_type, unit_types, city, country_id, certification_scheme_id, parcel_ids, start_date, end_date, activity_url, activity_hash.
  • CertificationNFT: the certificate of compliance, activity, certification scheme, certification body and audit report (each with id or name, URL and hash), country_id, issue_date, expiry_date, unit_types, certification_status, and the certified quantities: carbon_removals_under_baseline, soil_emissions_under_baseline, permanent_net_carbon_removal_benefit, carbon_farming_temporary_net_carbon_removal_benefit, carbon_farming_net_soil_emission_reduction_benefit, carbon_storage_temporary_net_carbon_removal_benefit. The quantities are decimal strings in tonnes CO2e, exactly as recorded on the certificate. An empty value means the certificate has none, and tokenURI leaves it out.
  • CarbonCreditBatchNFT: carbon_credit_batch_id, batch_name, unit_type, amount, monitoring_period_start_date, monitoring_period_end_date, status_code, issue_date, expiry_date, country_id, and the activity, operator, certificate of compliance, certification scheme and certification body it was issued under (each with URL and hash).

Token data is fixed by each contract's storage layout. Changing a token's fields means deploying a new contract; tokens minted on the old one stay there.

Carbon credit batches

A batch is the credits of one unit type issued for an activity over one monitoring period. A verified monitoring period produces one batch for each benefit field that has a value:

Benefit field on the verification batch_name unit_type
permanent_net_carbon_removal_benefit Permanent Removals Carbon Credit Batch Permanent Removal
carbon_farming_temporary_net_carbon_removal_benefit Carbon Farming Removals Carbon Credit Batch Carbon Farming Sequestration
carbon_farming_net_soil_emission_reduction_benefit Soil Emissions Reductions Carbon Credit Batch Soil Emission Reduction
carbon_storage_temporary_net_carbon_removal_benefit Carbon Storage in Product Carbon Credit Batch Carbon Storage in Product

When a batch is minted, it gets its own token-bound account (ERC-6551), and the batch's CarbonCredit units are minted into that account. One credit is one tonne CO2e: 6.5 tonnes is 6500000000000000000 base units.

  • The batch owns its credits. Only the current holder of the batch token can move credits out of its account, so selling the batch token hands over the credits with it.
  • amount is fixed at mint. It records what was issued. The live balance is CarbonCredit.balanceOf of the batch's account (tokenBoundAccount(tokenId)).
  • Credits taken out of a batch are pooled. In an ordinary wallet, credits from different batches are interchangeable and no longer traceable to a batch.

Who can do what

  • Minter: each contract has a single minter, the tokenizer's key. Only the minter can mint. It can burn CarbonCredit only from a holder who has approved it with ERC-20 approve, so it cannot take credits without consent.
  • Owner: each contract's owner can change the minter (setMinter). It cannot mint or move tokens.
  • Holders: tokens are minted to the operator's wallet and can be transferred like any ERC-721 or ERC-20 token.

Safe to repeat

Each contract allows one token per registry id: minting the same parcel_id, activity_id, certificate_of_compliance_id or carbon_credit_batch_id again is rejected. CarbonCredit.mintedTo(address) records the total ever minted to an address, and does not drop when credits are moved out. The tokenizer funds a batch against mintedTo, not the balance, so credits the owner has already moved out are never issued twice.

Looking up a token

Each NFT contract maps a registry id to its token id, returning 0 for an id that has not been minted:

  • ParcelNFT.tokenIdByParcelId(parcel_id)
  • ActivityNFT.tokenIdByActivityId(activity_id)
  • CertificationNFT.tokenIdByComplianceId(certificate_of_compliance_id)
  • CarbonCreditBatchNFT.tokenIdByBatchId(carbon_credit_batch_id)

The full record is returned by getParcel, getActivity, getCertification and getBatch, or as metadata by tokenURI. The OGCR Chain Cache mirrors every token into OBP (parcel_on_chain, activity_on_chain, ...), so they can also be read through the registry's APIs.

When each token is minted is decided by the tokenizer; see the "What the tokenizer mints, and when" table in OGCR Architecture.

Source: OGCR-Smart-Contracts



ogcr-tokenizer: polls OBP and mints a token to the operator's wallet when a record reaches a qualifying state (table below). Each token is minted exactly once, and a token waits until the tokens it depends on exist. It only reads from OBP and reports its health at /healthz.

OGCR-Chain-Cache: reads every OGCR token from the chain and writes one mirror record per token (parcel_on_chain, activity_on_chain, ...) into OBP, so on-chain state can be joined with off-chain records through the normal APIs. It owns the definitions of these entities and writes chain_sync_status after each run.

OGCR-App: the registry's public-facing pages and the marketplace (work in progress). Users log in with OIDC, and it reads and writes through OBP-API, never directly on chain.

OGCR Operator Platform: the application for operators, who run the carbon activities. Built by OGCR-GILAB (https://github.com/OGCR-GILAB/operator-platform, with its API service at https://github.com/OGCR-GILAB/operator-platform-api), it is a client of OBP-API.

OGCR Certification Platform: the application for certification bodies, who verify and certify activities. Built by MultiOne (ogcr-certification-platform, https://codeberg.org/OGCR-project/ogcr-certification-platform), it is a client of OBP-API.

OBP-MCP server: a Model Context Protocol server that lets AI agents discover and call OBP-API endpoints, including the endpoints generated for the registry's Dynamic Entities, and read the Glossary. Claude Code, Claude Desktop and IDE agents connect to it with the user's OAuth token; Opey connects with a Consent-JWT.

Opey Agent: OBP's AI assistant, available in the Portal and API Explorer. It calls OBP-API through the OBP-MCP server with a consent the user approves, so it can see and do only what that user's Roles allow. It can answer questions about the registry and help write App Studio pages.

What the tokenizer mints, and when

Token Minted when Also required
ParcelNFT parcel_owner_verification is verified parcel, parcel_activity, activity, operator
ActivityNFT activity_verification is verified and a certificate_of_compliance exists activity, operator
CertificationNFT a certificate_of_compliance is created, including each re-certification ActivityNFT, activity, operator, certification_scheme, certification_body
CarbonCreditBatchNFT + CarbonCredit activity_monitoring_period_verification is verified; one batch for each benefit field with a value ActivityNFT, certificate_of_compliance, certification_scheme, certification_body

Design rules

  • One gateway. All access to registry data goes through OBP-API, AI agents included, so authentication and Roles are enforced in one place.
  • One-way services. The tokenizer reads OBP and writes to the chain. The chain cache reads the chain and writes to OBP.
  • Safe to repeat. Minting is deduplicated on chain and mirror records are upserted, so a rerun never creates duplicates.

Source code

Every repository, with what it does. The OGCR DCR product site (https://ogcr-dcr-product.tesobe.com/#components) describes each of them, and its publish workflow checks that both name the same repositories, so keep one repository per line in the form - [Name](link): what it does.

To browse the registry's endpoints, open API Explorer II.

The OGCR Project has received funding from the European Union's Horizon Europe programme under grant agreement 101218854.

Why history is lost: coins and notes

The reason pooled credits lose their history isn't a shortcoming — it's the definition of being interchangeable. Something is fungible precisely because nobody records which one is which. There are two ways money handles this, and they lead to two different designs.

Coins

A euro coin has no identity. There is no record of which coin is which, and there never was. Tracing one is not difficult — it is impossible, permanently.

This is how credits behave today once they leave a batch.

Notes

A euro banknote carries a serial number. It still spends as freely as any other note, because in everyday use nobody looks — but the identity is there, and can be consulted when something goes wrong.

This is how established carbon registries work: credits carry serial numbers and trade as interchangeable.

The difference matters most when an activity is later found to be invalid. Under the coin model, credits that have already dispersed cannot be identified, so nothing can be done about them. Under the note model they remain identifiable no matter how many times they change hands.

The note model, in detail

Under consideration, not built. This section describes an approach OGCR is evaluating. It is not how the system behaves today.

In the note model, every credit carries a tag recording where it came from, and that tag travels with it through every transfer, forever. A holder's balance is then not a single number but a set of identifiable holdings:

Bob holds:

300 credits from batch #1

200 credits from batch #7

He has 500 credits in total — but not an anonymous 500. He has two holdings that can each still be traced to the activity that produced them.

Trading works normally: nothing is locked, there is no waiting period, and no permission is needed. The one change is that when Bob sells 400 credits he must say which 400 — exactly as handing over cash means handing over particular notes.

What it costs

Market depth. If every batch is separately tagged, buyers cannot simply order "1000 credits" — they buy from particular batches. That makes each individual market smaller. Established registries accept this because carbon is largely traded through negotiated, one-to-one deals rather than an open exchange.

How precise the tag should be

Traceability is a dial rather than a switch, and where it is set is the real decision:

Tag per batch — the most precise. Every credit traces to one activity. Smallest individual markets.
Tag per class — for example by credit type and vintage year. Credits are interchangeable within a class, and still traceable to that class. A middle position with far better market depth.
No tag — today's behaviour once credits leave a batch. One deep, single market, and no provenance at all.

The setting also decides what can be done when an activity is discredited. Tagged per batch, the affected credits can be identified exactly. Tagged per class, the affected holders can be identified and the loss shared proportionally across that class. Untagged, nothing can be done once the credits have dispersed.