Tokens — How it works
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, andtokenURIleaves 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.
amountis fixed at mint. It records what was issued. The live balance isCarbonCredit.balanceOfof 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 burnCarbonCreditonly from a holder who has approved it with ERC-20approve, so it cannot take credits without consent. - Owner: each contract's
ownercan 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, andtokenURIleaves 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.
amountis fixed at mint. It records what was issued. The live balance isCarbonCredit.balanceOfof 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 burnCarbonCreditonly from a holder who has approved it with ERC-20approve, so it cannot take credits without consent. - Owner: each contract's
ownercan 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.
- OBP-API: The registry gateway
- OGCR-DynamicEntities: Builds the data model
- OGCR-App: Registry pages and marketplace
- OGCR-GILAB Operator Platform: App for activity operators
- OGCR-GILAB Operator Platform API: The Operator Platform's API service
- ogcr-certification-platform: App for certification bodies
- ogcr-tokenizer: Mints verified records
- OGCR-Smart-Contracts: The token contracts
- OGCR-Chain-Cache: Mirrors tokens into the registry
- OBP-OIDC: OpenID Connect provider
- OBP Keycloak Provider: Lets Keycloak log people in with their OBP-API accounts
- OBP-MCP server: MCP server for AI agents
- Opey Agent: OBP's AI assistant
- OBP Senti: Agentic security and performance checking
- OBP Portal and API Manager: Consumer registration and administration
- API Explorer II: Browse and try the registry's endpoints
- OGCR-Charts: Helm charts to deploy the OGCR platform on Kubernetes
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:
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.