[carbon] Review Toucan contracts re: changes for puro.earth credits

[jabby09]

Contracts are here: https://app.toucan.earth/contracts

Need to review contacts for changes related to supporting puro.earth credits and if there is any impact on KlimaDAO or Carbonmark technology stack. i.e. are any changes required for:

• RA contract
  • Add a new facet for Escrowable TCO2 contracts
    • In particular, call requestRetirement with the appropriate params isntead of the simple synchronous retirement function
  • Configure the facet for the Puro TCO2 contract factory
• CM contract
  • Add logic to handle full-batch listings - at least for now they are batch NFTs, NOT fractionalized TCO2s, which only allow full batch purchases
  • Configure Puro TCO2 contracts to be eligible for full-batch listings
• Subgraphs
  • Add Puro contract events to polygon-digital-carbon subgraph and handle escrow logic (e.g. separate entity for RetirementRequest and Tokenize/Detokenize request/finalization
  • Update Carbonmark subgraph if necessary to track Puro listings
• APIs
  • Add necessary logic to handle retirement requests, reversions, and finalizations
  • Add necessary logic to handle full-batch listings
• UI/FE
  • Update the retirement pages, esp. the receipt, to handle 'reverted', 'not yet finalized', and 'finalized' states
  • Update listing page to indicate full-batch purchases (i.e. no fractionalization, must purchase entire amount of a listing)

[0xAurelius]

So there are two Puro specific contracts:

1. PuroToucanCarbonOffsets: https://polygonscan.com/address/0x17179596dd44167743f707F590E34C49caBe4E7D#code
2. PuroToucanCarbonOffsetsFactory: https://polygonscan.com/address/0xc83dc91b3cd45d65f981c0018b3eb1c43a468381#code

#2 is essentially identical to the current implementation of the Verra TCO2's base factory contract, just with a different standard hard-coded (Puro instead of Verra)

#1 has some additional Escrowable functionality, including detokenization and a staged retirement process - the retirement is at first initiated in much the same way as the original TCO2 but via a function called requestRetirement - which can then either be finalized or reverted by a set of permissioned functions

From the contract code it's not clear if the finalization/reversion process is automated by an off-chain process that interacts with Puro's registry API or if Toucan must manually approve each retirement. I assume it's automated, but we should confirm that with their tech team, as well as ask them what the expected round-trip finalization time is so we can set expectations with our users

This means on the frontend we'll need to account for the fact that Puro retirements are not finalized when the Polygont transaction initiating them is confirmed, but only after the corresponding RetirementFinalized event is emitted

[Atmosfearful]

So to recap then the scope of work on our end is:

1. Update the subgraph to track 'finalization/reversion' events and add those states to the schema
2. Update the FE retirement pages to handle 'reverted', 'not yet finalized', and 'finalized' states

We still plan to generate the complete retirement page after the initial transaction and not wait for finalization to generate it.

Any other work I'm missing? Looks like Cujo captured some of these as to-dos already?

[0xAurelius]

Well the RA contract and CM contract itself will also need some attention to handle the new token contracts:
3. Add RA functionality to handle requestRetirement on the Puro TCO2 contracts and configure diamond to route properly
4. Make sure CM listings of the Puro TCO2 contracts can be created (this should be negligible but likely will need to add a contract address to the config)

I'll do my best to update the initial issue's to-do items based on my understanding

Also: we heard back from Toucan, the retirement finalization process is manual for now, will be automated at some point but no solid ETA

So we need to assume the retirement finalization events may take hours or even days to arrive... which means full async

[0xAurelius]

There is also the issue of "full batch" listings - since these are not fractionalized and can only be retired in the original full batch, I think CM should only allow purchases of the full batch (at least until Toucan allows retirement of fractional batches...)

[Atmosfearful]

As discussed today on our call, this workstream is in a holding pattern until we get more info on timelines for supporting fractional retirements

Other things that come to mind:

• We may need to plan for customers running into a failed retirement, after paying with fiat via Retire Now.
  I assume the contract takes it out of escrow and puts it back in the users wallet? that's a bit of a nightmare the way our current fiat tooling works w/ a single server wallet doing the txn
• I am also starting to think the best way to approach this would be a new event + Subgraph entity called RetirementRequest so that we don't pollute our KlimaRetire entitiess in the subgraph with things that aren't retirements per-se, same goes for /retirements api resources, and /retirements pages

[Atmosfearful]

Latest update after a policy/engineering sync today:

SC functionality is done. 3 new fields available - need to be added to subgraph.

• Consumption country code

• Consumption start

• Consumption stop

• Ask Toucan if these fields are necessary for retirements to be completed

  • @cujo klima will reach out or tag in @0xAurelius to find out

• Remaining subgraph changes:

  • Update schemas to add these 3 new fields.
  • Need to push puro projects to CMS and to IPFS.
  • Add Puro contracts to subgraph to track for holdings etc.