# Retiring Credits Onchain 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: ```solidity 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: ```typescript 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](https://documentation.carbonregistry.com/documentation/api/endpoints/v0.5/projects#refresh-carbonregistry.coms-onchain-transaction-indexers) 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: ```typescript 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](https://documentation.carbonregistry.com/documentation/api/endpoints/v0.5/projects#finalize-a-retirement), 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 -> An example of an official CarbonRegistry.com retirement certificate ->