API Explorer

OGCR Architecture

dynamic

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.

<details> <summary style="display:list-item;cursor:s-resize;">OGCR Smart Contracts</summary>

<p>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.</p> <h3><a href="#the-token-family">The token family</a></h3> <pre><code>ParcelNFT ──────────────┐ v ActivityNFT <── CertificationNFT (one per certificate; a ^ re-certification adds one) │ CarbonCreditBatchNFT ── owns ──> token-bound account (ERC-6551) │ holds v CarbonCredit (ERC-20) </code></pre> <table> <thead> <tr><th>Contract </th><th> Standard </th><th> Symbol </th><th> One token per </th></tr> </thead> <tbody> <tr><td><code>ParcelNFT</code> </td><td> ERC-721 </td><td> PARCEL </td><td> <code>parcel_id</code> </td></tr> <tr><td><code>ActivityNFT</code> </td><td> ERC-721 </td><td> ACT </td><td> <code>activity_id</code> </td></tr> <tr><td><code>CertificationNFT</code> </td><td> ERC-721 </td><td> CERT </td><td> <code>certificate_of_compliance_id</code> </td></tr> <tr><td><code>CarbonCreditBatchNFT</code> </td><td> ERC-721 + ERC-6551 </td><td> CCB </td><td> <code>carbon_credit_batch_id</code> </td></tr> <tr><td><code>CarbonCredit</code> </td><td> ERC-20, 18 decimals </td><td> CC </td><td> (fungible) </td></tr> <tr><td><code>CarbonERC6551Registry</code>, <code>CarbonERC6551Account</code> </td><td> ERC-6551 </td><td> </td><td> infrastructure for the batch accounts </td></tr> </tbody> </table> <p><code>ActivityNFT</code> records the parcels linked to the activity (<code>parcel_ids</code>). <code>CertificationNFT</code> and <code>CarbonCreditBatchNFT</code> point at their activity's token (<code>activity_nft_id</code>). A re-certification is a new <code>certificate_of_compliance</code> record, so it mints a new <code>CertificationNFT</code> for the same activity.</p> <h3><a href="#what-a-token-stores">What a token stores</a></h3> <p>Each token stores its record's fields on chain, and <code>tokenURI</code> returns them as ERC-721 metadata (<code>data:application/json;base64,...</code>), so no off-chain metadata server is needed.</p> <p>Fields ending in <code>_url</code> or <code>_uri</code> link to the registry record on OBP-API. Fields ending in <code>_hash</code> are the keccak256 hash of the registry's response body for that record at mint time.</p> <ul> <li><strong>ParcelNFT</strong>: <code>parcel_id</code>, <code>parcel_uri</code>, <code>parcel_hash</code>.</li> <li><strong>ActivityNFT</strong>: <code>activity_id</code>, <code>operator_id</code>, <code>operator_name</code>, <code>name</code>, <code>summary</code>, <code>website</code>, <code>activity_type</code>, <code>unit_types</code>, <code>city</code>, <code>country_id</code>, <code>certification_scheme_id</code>, <code>parcel_ids</code>, <code>start_date</code>, <code>end_date</code>, <code>activity_url</code>, <code>activity_hash</code>.</li> <li><strong>CertificationNFT</strong>: the certificate of compliance, activity, certification scheme, certification body and audit report (each with id or name, URL and hash), <code>country_id</code>, <code>issue_date</code>, <code>expiry_date</code>, <code>unit_types</code>, <code>certification_status</code>, and the certified quantities: <code>carbon_removals_under_baseline</code>, <code>soil_emissions_under_baseline</code>, <code>permanent_net_carbon_removal_benefit</code>, <code>carbon_farming_temporary_net_carbon_removal_benefit</code>, <code>carbon_farming_net_soil_emission_reduction_benefit</code>, <code>carbon_storage_temporary_net_carbon_removal_benefit</code>. The quantities are decimal strings in tonnes CO2e, exactly as recorded on the certificate. An empty value means the certificate has none, and <code>tokenURI</code> leaves it out.</li> <li><strong>CarbonCreditBatchNFT</strong>: <code>carbon_credit_batch_id</code>, <code>batch_name</code>, <code>unit_type</code>, <code>amount</code>, <code>monitoring_period_start_date</code>, <code>monitoring_period_end_date</code>, <code>status_code</code>, <code>issue_date</code>, <code>expiry_date</code>, <code>country_id</code>, and the activity, operator, certificate of compliance, certification scheme and certification body it was issued under (each with URL and hash).</li> </ul> <p>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.</p> <h3><a href="#carbon-credit-batches">Carbon credit batches</a></h3> <p>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:</p> <table> <thead> <tr><th>Benefit field on the verification </th><th> <code>batch_name</code> </th><th> <code>unit_type</code> </th></tr> </thead> <tbody> <tr><td><code>permanent_net_carbon_removal_benefit</code> </td><td> Permanent Removals Carbon Credit Batch </td><td> Permanent Removal </td></tr> <tr><td><code>carbon_farming_temporary_net_carbon_removal_benefit</code> </td><td> Carbon Farming Removals Carbon Credit Batch </td><td> Carbon Farming Sequestration </td></tr> <tr><td><code>carbon_farming_net_soil_emission_reduction_benefit</code> </td><td> Soil Emissions Reductions Carbon Credit Batch </td><td> Soil Emission Reduction </td></tr> <tr><td><code>carbon_storage_temporary_net_carbon_removal_benefit</code> </td><td> Carbon Storage in Product Carbon Credit Batch </td><td> Carbon Storage in Product </td></tr> </tbody> </table> <p>When a batch is minted, it gets its own token-bound account (ERC-6551), and the batch's <code>CarbonCredit</code> units are minted into that account. One credit is one tonne CO2e: 6.5 tonnes is <code>6500000000000000000</code> base units.</p> <ul> <li><strong>The batch owns its credits.</strong> 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.</li> <li><strong><code>amount</code> is fixed at mint.</strong> It records what was issued. The live balance is <code>CarbonCredit.balanceOf</code> of the batch's account (<code>tokenBoundAccount(tokenId)</code>).</li> <li><strong>Credits taken out of a batch are pooled.</strong> In an ordinary wallet, credits from different batches are interchangeable and no longer traceable to a batch.</li> </ul> <h3><a href="#who-can-do-what">Who can do what</a></h3> <ul> <li><strong>Minter</strong>: each contract has a single <code>minter</code>, the tokenizer's key. Only the minter can mint. It can burn <code>CarbonCredit</code> only from a holder who has approved it with ERC-20 <code>approve</code>, so it cannot take credits without consent.</li> <li><strong>Owner</strong>: each contract's <code>owner</code> can change the minter (<code>setMinter</code>). It cannot mint or move tokens.</li> <li><strong>Holders</strong>: tokens are minted to the operator's wallet and can be transferred like any ERC-721 or ERC-20 token.</li> </ul> <h3><a href="#safe-to-repeat">Safe to repeat</a></h3> <p>Each contract allows one token per registry id: minting the same <code>parcel_id</code>, <code>activity_id</code>, <code>certificate_of_compliance_id</code> or <code>carbon_credit_batch_id</code> again is rejected. <code>CarbonCredit.mintedTo(address)</code> records the total ever minted to an address, and does not drop when credits are moved out. The tokenizer funds a batch against <code>mintedTo</code>, not the balance, so credits the owner has already moved out are never issued twice.</p> <h3><a href="#looking-up-a-token">Looking up a token</a></h3> <p>Each NFT contract maps a registry id to its token id, returning 0 for an id that has not been minted:</p> <ul> <li><code>ParcelNFT.tokenIdByParcelId(parcel_id)</code></li> <li><code>ActivityNFT.tokenIdByActivityId(activity_id)</code></li> <li><code>CertificationNFT.tokenIdByComplianceId(certificate_of_compliance_id)</code></li> <li><code>CarbonCreditBatchNFT.tokenIdByBatchId(carbon_credit_batch_id)</code></li> </ul> <p>The full record is returned by <code>getParcel</code>, <code>getActivity</code>, <code>getCertification</code> and <code>getBatch</code>, or as metadata by <code>tokenURI</code>. The OGCR Chain Cache mirrors every token into OBP (<code>parcel_on_chain</code>, <code>activity_on_chain</code>, ...), so they can also be read through the registry's APIs.</p> <p>When each token is minted is decided by the tokenizer; see the "What the tokenizer mints, and when" table in OGCR Architecture.</p> <p>Source: <a href="https://github.com/OpenBankProject/OGCR-Smart-Contracts">OGCR-Smart-Contracts</a></p>

</details>

<br></br>

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.