Retiring Credits Onchain

CarbonRegistry.com credits can be permissionlessly retired onchain without using CarbonRegistry.com APIs. Follow the guidelines below to complete the process.

CarbonRegistry.com enables the permissionless retirement of credits issued on its platform. Users can take full control of their credits by transferring them to their own wallets, portfolio managers, or onchain solutions, without losing the ability to retire the credits. As long as the required data is provided when the retirement function is executed, the process will generate an official retirement certificate on CarbonRegistry.com.

The Project Contract's Retire Function

To retire CarbonRegistry.com credits onchain, call the retire function on the project contract that issued the credits:

function retire(
    uint256 tokenId, // The ID of the exPost credits to be retired
    uint256 amount,  // The amount of credits to be retired, where 1 tCO2-e = 10^18 tokens
    address beneficiary, // The wallet address that will receive the retirement NFT
    string memory retireeName, // Name to be displayed on the official CarbonRegistry.com retirement certificate
    string memory customUri, // Optional: Off-chain data URI for the retirement NFT
    string memory comment, // Comment to be displayed on the CarbonRegistry.com retirement certificate
    bytes memory data // Data required to generate the CarbonRegistry.com retirement certificate (see format below)
) external returns (uint256 nftTokenId) ;

Only the wallet address that holds the credits can call this function. When using this permissionless onchain method, it's essential that the transaction includes the required data for the retirement certificate. Without this, the certificate may remain in an unfinalized state.

Note: The data parameter is not stored onchain, but the retireeName, customUri, and comment are saved as onchain metadata in the generated retirement NFT. Even though data isn’t onchain, it plays a crucial role in creating the retirement certificate on CarbonRegistry.com.

Retire Function Data Parameter

The data parameter in the retire function call should always be included, as it contains key information used to generate the retirement certificate. This parameter should include the beneficiary, reason, and comment for the retirement. If the retirement is part of a marketplace transaction or on behalf of an organization on CarbonRegistry.com, the organizationId (the organization's account ID on CarbonRegistry.com) should also be provided.

Here’s an example of how to generate the data field using Node.js:

const beneficiary = "ICR";
const reason = "Voluntary purposes";  // See options for this value below.
const comment = "Retiring credits for activities in 2023";
const organizationId = "e74b0f84-0023-4bfb-bdec-ba3d2b99197e";

const data = ethers.toUtf8Bytes(
  JSON.stringify({
    beneficiary: beneficiary,
    reason: reason,
    comment: comment,
    organizationId: organizationId  // Optional, depending on transaction context
  })
);

This data variable can then be passed into the transaction when calling the retire function. Once the transaction is processed by a node, CarbonRegistry.com’s indexer will pick it up and generate the retirement certificate, which may take up to 15 minutes. If you need faster certificate generation, you can ping our indexer refresh endpoint.

Retirement Data Restrictions and Guidelines

When passing retirement certificate data to the retire function, ensure that all fields are provided according to the following guidelines and restrictions:

• beneficiary: A short string representing the retiree's name, recommended to be under 100 characters.

• comment: A string where the beneficiary can add custom text to be displayed on the retirement certificate, with a recommended limit of 500 characters.

• reason: Must be one of the following predefined options:

  • Compliance

  • Corsia

  • Voluntary purposes

  • Overall mitigations of global emissions

  • Corporate emission compensation

  • Other

  • Article 6.2

  • Testing

Unfinalized Retirements

If a retirement was processed without the necessary data (beneficiary, reason, and comment), it will be marked as unfinalized on CarbonRegistry.com. However, in many cases, you can still finalize the retirement if you can prove ownership of the retirement certificate or the private key that signed the transaction.

To finalize, you must create a signature proving that you either hold the retirement certificate NFT or control the wallet that signed the original retirement transaction. Below is an example using ethers.js for frontend signing:

const beneficiary = "ICR";
const reason = "Voluntary purposes";  // Choose from the predefined options
const comment = "Retiring credits for activities in 2023";
const projectAddress = "0x77be59acfef85a1578a5996d06b48b6ee1bac29c";
const nftTokenId = "47";  // The retirement certificate NFT tokenId

const signatureMessage = `${beneficiary};;${comment};;${reason};;${projectAddress};;${nftTokenId}`;
const signer = await provider.getSigner();  // Ensure provider is initialized
const signature = await signer.signMessage(signatureMessage);

const carbonRegistryResponse = await axios.post("https://api.carbonregistry.com/retirements/finalize", {
    signer: "0xd00749D7eb0D333D8997B0d5Aec0fa86cf026c76",  // Signer of the signature
    signature,
    signedData: {
        comment,
        reason,
        beneficiary,
        projectAddress,
        tokenId: nftTokenId
    }
}, {
    headers: {
        Authorization: `Bearer %Carbon_Registry_Access_token%`
    }
});

This signature and signed data are then submitted to CarbonRegistry.com’s finalize endpoint, allowing the retirement to be completed.

Testing Data

When testing this functionality in production you should use the name of your organization as beneficiary , the value Testing for reason .

Retirement Examples on CarbonRegistry.com

An example of a retirement transaction -> https://www.carbonregistry.com/transactions/4c95045f-dd40-4edf-b009-af1a5e8239d8

An example of an official CarbonRegistry.com retirement certificate -> https://www.carbonregistry.com/retirements/certificate/46-0x77be59acfef85a1578a5996d06b48b6ee1bac29c