API Explorer

OGCR Smart Contracts

dynamic

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