Retirement certificates
Retirement certificates
The RetirementCertificates
contract lets users mint NFTs that act as proof of retirement. These NFTs display how many TCO2 tokens a user has retired, along with retirement details such as the beneficiary of the retirement and a message. This contract extends ERC721 and is upgradeable.
Note that minting NFTs directly via the RetirementCertificates
contract is only supported for Verra retirements. For Puro retirements, users can only request a retirement that will then need to be processed by Toucan offchain in the Puro registry, before finalizing onchain by minting the certificate to the retirer.
If you are interested in building on top of Puro retirements, we recommend using fractional retirements as that model can accommodate sub-tonnage retirement use cases.
mintCertificate
Mints a new RetirementCertificates
NFT based on existing Retired
events. The function can either be called by a valid TCO2
contract (in its retireAndMintCertificate()
function), or by a user who owns Retired
events.
Note: This information is publicly written to the blockchain in plaintext.
Params
retiringEntity
address
The entity that has retired TCO2 and is eligible to mint an NFT
retiringEntityString
string
An identifiable string for the retiring entity, e.g. their name
beneficiary
address
The address of the beneficiary to set in the NFT
beneficiaryString
string
An identifiable string for the beneficiary to set in the NFT, e.g. their name
retirementMessage
string
A retirement message to be set in the NFT
retirementEventIds
uint256[]
An array with with event IDs to associate with the NFT
attachRetirementEvents
This function allows you to attach the Retired
events to a RetirementCertificates
NFT.
For context, if you go back to the TCO2 contract docs you will see that you are able to retire TCO2 without minting a RetirementCertificates
, but you do get a retirementEventId
.
This allows you to update the amount in an existent RetirementCertificates
NFT with new retirements.
Params
tokenId
uint256
The ID of the RetirementCertificate
NFT to attach events to
retirementEventIds
uint256[]
An array with with event IDs to associate with the NFT
getUserEvents
Fetches all the Retired
events that a given user owns.
Params
user
address
The address of the user for whom to fetch all events.
Return Values
retirementEventIds
uint256[]
The IDs of the events owned by the given user.
updateCertificate
This function allows you to update the retirementMessage
, beneficiary
, and beneficiaryString
of a RetirementCertificates
NFT within 24 hours of creation. Empty param values are ignored, and will not overwrite the existing stored values in the NFT.
Params
tokenId
uint256
The ID of the RetirementCertificates
NFT to update
retiringEntityString
string
An identifiable string for the retiring entity, e.g. their name
beneficiary
address
The address of the beneficiary to set in the NFT
beneficiaryString
string
An identifiable string for the beneficiary to set in the NFT, e.g. their name
retirementMessage
string
A retirement message to be set in the NFT
getRetiredAmount
This function returns the amount of TCO2 tokens retired by a user that's associated with a given RetirementCertificates
NFT. The function sums up all the retirement amounts from all of event IDs attached to the RetirementCertificate.
Params
tokenId
uint256
The ID of the RetirementCertificates
NFT to fetch the amount for
Return Values
amount
uint256
The amount of retired TCO2 tokens associated with that tokenId
Fractional retirements
Fractional retirements are currently supported only on Base Sepolia
The Puro registry supports retirements only of tonne denominations, hence we have extended our protocol to support franctionalizing retirement certificate NFTs so we can enable sub-tonnage retirement use cases. There are two new contracts involved in fractionalizing a RetirementCertificates
NFT:
RetirementCertificateFractionalizer
, an ERC1155 contract that fractionalizes certificates and keeps track of fractional balances. These balances represent the right to mint a fractional retirement certificate, they are not an environmental claimRetirementCertificateFractions
, an ERC721 contract that is used to mint fractional retirement certificates. Minting such a certificate can only be done by an account that holds or has been approved to useRetirementCertificateFractionalizer
balance. In order to mint a fractional certificate, the equivalent amount ofRetirementCertificateFractionalizer
balance is burnt
How to fractionalize a certificate
On a high level, Alice has to retire a Puro TCO2 on behalf of RetirementCertificateFractionalizer
. Alice can then send her RetirementCertificates
NFT to the RetirementCertificateFractionalizer
. The act of transferring a RetirementCertificates
NFT to the fractionalizer plus the fact that the fractionalizer is set as the beneficiary of the certificate allows the fractionalizer to mint an ERC1155 balance to Alice.
Alice can then list her ERC1155 balance on any NFT marketplace from where it can be bought by whomever needs to do a fractional retirement. We invite the community to come up with novel mechanisms to buy and sell RetirementCertificateFractionalizer
liquidity.
Concretely:
Request a retirement by using any available TCO2 balance in the
My Carbon Assets
section and include the following information:Beneficiary wallet address
: Set this to the address of theRetirementCertificateFractionalizer
(found in theContracts
page – ensure the correct network tab is selected).Beneficiary name or organization name
: Set this to the output ofRetirementCertificateFractionalizer.beneficiaryString()
, formatted asTOUCAN-2.0-RCS-[CHAIN_ID]
, where[CHAIN_ID]
represents the chain ID of the current chain.
Once the retirement is finalized by Toucan, transfer the newly minted
RetirementCertificates
NFT to theRetirementCertificateFractionalizer
contract. The transfer should mint the equivalent amount of ERC1155 balance to your account.
Each RetirementCertificateFractionalizer
token id maps to the respective CarbonProjectVintages
token id on the same chain.
How to retire fractional balance
You can acquire RetirementCertificateFractionalizer
balance on Base Sepolia via OpenSea.
Once you hold RetirementCertificateFractionalizer
balance, you can retire it and mint a RetirementCertificateFractions
NFT by calling mintFraction
on the fractionalizer contract.
RetirementCertificateFractionalizer
FractionRequestData
mintFraction
Mint a fraction of a retirement certificate, from the balance of the caller
Parameters
params
struct FractionRequestData
The request data of the fraction to mint
Return Values
fractionTokenId
uint256
The id of the minted fraction NFT, in the fractions contract
mintFractionFrom
Mint a fraction of a retirement certificate, from the balance of the listing owner
Parameters
from
address
The owner of the balance to mint the fraction from
params
struct FractionRequestData
The request data of the fraction to mint
Return Values
fractionTokenId
uint256
The id of the minted fraction NFT, in the fractions contract
Last updated