# Toucan Protocol in depth
This in depth Toucan Protocol summary has the following section.
1. [Creating TCO2 tokens](https://hackmd.io/Z06Ad5ezTga8sOsqh3DvkA#Creating-TCO2-tokens)
2. Creating BCT tokens
3. Retiring TCO2 tokens

## Creating TCO2 tokens
### 1. CarbonOffsetBatches.mintEmptyBatch()
#### Overview
- increments `batchTokenCounter`
- creates new `newItemId` from `batchTokenCounter`
- mint ERC721 token on the basis of the `newItemId` as `tokenId` to the address provided in the parameters
- set retirement status of newly minted token to `RetirementStatus.Pending`

*All the mappings and state variables are stored in the contract `CarbonOffsetBatchesStorage.sol`. [link to file](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonOffsetBatchesStorage.sol)*
#### Inputs
1. `to`: `Address` - Address to which the ERC721 token is to be minted

#### Require & Modifiers
- `whenNotPaused` - contract can not be paused

#### Output
None
#### Events
` event BatchMinted(address sender, uint256 tokenId);
`
#### Function Prototype

function mintEmptyBatch(address to) external virtual whenNotPaused {

*[link to function](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonOffsetBatches.sol#L236)*
### 2. CarbonProject.addNewProject()
#### Overview
- sets new `projectId` to true in various mappings
- increments `totalSupply` & `projectTokenCounter`
- creates `newItemId` from `projectTokenCounter` and stores in a mapping
- mint ERC721 token on the basis of the `newItemId` as `tokenId` to the address provided in the parameters
- stores all the parameters in the mapping `projectData[newItemId]...`

*All the mappings and state variables are stored in the contract `CarbonProjectStorage.sol`. [link to file](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonProjectsStorage.sol)*
#### Inputs
1. `to`: `Address` - Address to which the ERC721 token is to be minted
2. `projectId`: `String` - **Question** this data is either from off-chain carbon offset companies or created through Toucan? Same for all below
3. `standard` : `String` -
4. `methodology`: `String` -
5. `region `: `String` -
6. `storageMethod`: `String` -
7. `method`: `String` -
8. `emissionType`: `String` -
9. `category`: `String` -
10. `uri`: `String` - metadata

#### Require & Modifiers
- `whenNotPaused` - contract can not be paused
- `onlyManager` - can only be called by the owner or address with `MANAGER_ROLE` role
- `projectId` != `''`
- `projectId` can not already exist

#### Output
- `newItem`: `uint256` - new project token ID that has been used as `tokenId` to mint the Carbon Project ERC721

#### Events
`event ProjectMinted(address receiver, uint256 tokenId);
`
#### Function prototype

 function addNewProject(
        address to,
        string memory projectId,
        string memory standard,
        string memory methodology,
        string memory region,
        string memory storageMethod,
        string memory method,
        string memory emissionType,
        string memory category,
        string memory uri
    ) external virtual override onlyManagers whenNotPaused returns (uint256)

*[link to function](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonProjects.sol#L104)*

### 3. CarbonProjectVintage.addNewVintage()
#### Overview
- sets new `projectId` to true in various mappings
- increments `totalSupply` & `projectVintageTokenCounter`
- creates `newItemId` from `projectVintageTokenCounter` and stores in a mapping
- mint ERC721 token on the basis of the `newItemId` as `tokenId` to the address provided in the parameters
- stores all the parameters in the mapping `vintageData[newItemId]...`
- stores the `newItemId` to the mapping `pvTokTokenId[projectTokenId][startTime]`

*All the mappings and state variables are stored in the contract `CarbonProjectVintageStorage.sol`. [link to file](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonProjectVintagesStorage.sol)*
#### Inputs
1. `to`: `Address` - Address to which the ERC721 token is to be minted
2. `projectTokenId`: `uint256` - `tokenId` used in creation of the Carbon Project ERC721
3. `name` : `string` - Name of the Carbon Project Vintage on the
4. `startTime`: `uint64` - Start time of the duration of the vintage
5. `endTime `: `uint64` - End time or experation time of the vintage
6. `totalVintageQuantity`: `uint64` - Amount of Vintage to be retired
7. `isCorsiaCompliant`: `bool` -
8. `isCCPcompliant`: `bool` -
9. `coBenefits`: `string` -
10. `correspAdjustment`: `string` -
11. `additionalCertification`: `string` -
12. `uri`: `string` - metadata

#### Require & Modifiers
- `whenNotPaused` - contract can not be paused
- `onlyManager` - can only be called by the owner or address with `MANAGER_ROLE` role
- `startTime < endTime`
- `pvToTokenId[projectTokenId][startTime] == 0` - Vintage already added

#### Output
- `newItem`: `uint256` - new project vintage token ID that has been used as `tokenId` to mint the Carbon Project ERC721

#### Events

event ProjectVintageMinted(
        address receiver,
        uint256 tokenId,
        uint256 projectTokenId,
        uint64 startTime
    );

#### Function prototype

 function addNewVintage(
        address to,
        uint256 projectTokenId,
        string memory name,
        uint64 startTime,
        uint64 endTime,
        uint64 totalVintageQuantity,
        bool isCorsiaCompliant,
        bool isCCPcompliant,
        string memory coBenefits,
        string memory correspAdjustment,
        string memory additionalCertification,
        string memory uri
    ) external virtual override onlyManagers whenNotPaused returns (uint256) 

*[link to function](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonProjectVintages.sol#L101)*
### 4.CarbonOffsetBatches.updateBatchWithData()
#### Overview
- sets `seriealNumber` & `quantity`

*All the mappings and state variables are stored in the contract `CarbonOffsetBatchesStorage.sol`. [link to file](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonOffsetBatchesStorage.sol)*
#### Inputs
1. `tokenId`: uint256 - ID of the project vintage ERC721 token
2. `serialNumber`: `string` - official serial number returned when retiring the carbon offset off-chain
3. `quantity`: `uint256` - amount that has been retired off-chain, to be transferred on-chain
4. `uri`: `string` - metadata

#### Require & Modifiers
- `whenNotPaused` - contract can not be paused
- `msg.sender` == `owner` || `msg.sender` == `VERIFIER_ROLE`
- batchNFT status != ` RetirementStatus.Confirmed`
- `serialNumber` != already been approved
- `URIs[uri]` == `false` - metadata does not already exist
#### Output
None
#### Events

event BatchUpdated(uint256 tokenId, string serialNumber, uint256 quantity);

#### Function prototype

function updateBatchWithData(
        uint256 tokenId,
        string memory serialNumber,
        uint256 quantity,
        string memory uri
    ) public virtual whenNotPaused

*[link to function](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonOffsetBatches.sol#L247)*
### 5.CarbonOffsetBatches.confirmRetirementWithVintage()
#### Overview
- stores the `projectVintageTokenId` into the mapping `nftList[tokenId]`
- - sets the serial number to `true`, so retirement can not be double spend
- sets the retirement to `RetirementStatus.Confirmed` for the BatchNFT

*All the mappings and state variables are stored in the contract `CarbonOffsetBatchesStorage.sol`. [link to file](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonOffsetBatchesStorage.sol)*
#### Inputs
1. `tokenId`: `uint256` - Batch token ID to confirm the retirement on
2. `projectVintageTokenId`: `uint256` - Project Vintage token ID to link the BatchNFT to
#### Require & Modifiers
- `whenNotPaused` - contract can not be paused
- - `onlyvVerifier` - can only be called by the owner or address with `VERIFIER_ROLE` role
- `nftList[tokenId].status` != `RetirementStatus.Confirmed` - Can not retire BatchNFT twice
- `nftList[tokenId].projectVintageTokenId` != `0` - cannot retire batch without project vintage
- check if the `projectVintageTokenId` exists in the `contractRegistry`
- `tokenId` exists
- `serialNumberExist[nftList[tokenId].serialNumber]` == `false` - serial number cannot already been approved
#### Output
None
#### Events

event BatchLinkedWithVintage(
        uint256 tokenId,
        uint256 projectVintageTokenId
    );

#### Function prototype

function confirmRetirementWithVintage(
    uint256 tokenId,
    uint256 projectVintageTokenId
) public virtual onlyVerifier whenNotPaused

*[link to function](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonOffsetBatches.sol#L200)*
### 6.ToucanCarbonOffsetsFactory.deployFromVintage()
#### Overview
- creates signature and payload that will be used to deploy new TCO2 contract, on the basis of `projectVintageTokenId`
- deployes new TCO2 contract and adds it's address to the `ToucanContractRegistry`
- stored the address in local array `deployedContracts` and mapping `pvIdtoERC20[projectVintageTokenId]`

*All the mappings and state variables are stored in the contract `ToucanCarbonOffsetsFactoryStorage.sol`. [link to file](https://github.com/CO2ken/contracts/blob/main/contracts/ToucanCarbonOffsetsFactoryStorage.sol)*
#### Inputs
1. `projectVintageTokenId`: `uint256` - token ID from the ERC721 project vintage token
#### Require & Modifiers
- `whenNotPaused` - contract can not be paused
- `beacon` != `address(0)` - beacon that tracks the current implementation has not been set
- `!checkExistence(projectVintageTokenId)` - check that `projectVintageTokenId` has not already been used to create a TCO2 contract
- check if the `projectVintageTokenId` exists in the `contractRegistry`
#### Output
None
#### Events

event TokenCreated(uint256 vintageTokenId, address tokenAddress);

#### Function prototype

function deployFromVintage(uint256 projectVintageTokenId)
        public
        virtual
        whenNotPaused

[*link to function*](https://github.com/CO2ken/contracts/blob/main/contracts/ToucanCarbonOffsetsFactory.sol#L128)
### 7.CarbonOffsetBatches.fractionalize()
#### Overview
- transfers the BatchNFT that is linked to the project vintage to the `ToucanCarbonOffset` contract to be fractionalized
#### Inputs
1. `tokenId`: `uint256` - token ID to be transferred
#### Require & Modifiers
- `_isApprovedOrOwner(_msgSender(), tokenId)` - ERC721 token is approved by the owner, or transfer is called by the owner self
- `nftList[tokenId].status` == `RetirementStatus.Confirmed` - retirement has been confirmed for the BatchNFT token linked to the `tokenId`
#### Output
None
#### Events
None
#### Function prototype

function fractionalize(uint256 tokenId) external virtual

[*link to function*](https://github.com/CO2ken/contracts/blob/main/contracts/CarbonOffsetBatches.sol#L363)
### 8. ToucanCarbonOffset.onERC721Received()
*This function gets triggerd after the function `fractionalize` has been called*
#### Overview
- check if the attributes of the received ERC721 token matches the attributes stored in the TCO2 contract
- stores the `tokenId` in the mapping `minterToId[from]`
- mint the quantity ERC20 tokens that match the quantity offset to the `from` address

*All the mappings and state variables are stored in the contract `ToucanCarbonOffsetsStorage.sol`. [link to file](https://github.com/CO2ken/contracts/blob/main/contracts/ToucanCarbonOffsetsStorage.sol)
#### Inputs
1. `address` - /* operator */
2. `from`: `address` - msg.sender
3. `tokenId`: `uint256` - token ID of the BatchNFT
4. `bytes calldata` - /* data */
#### Require & Modifiers
- `whenNotPaused` - contract can not be paused
- ` checkWhiteListed(msg.sender)` - the BatchNFT is from a whitelisted TCO2 contract
- `checkMatchingAttributes(projectVintageTokenId)` - the attributes of the TCO2 contract match the once from the received ERC721 token
- `status == RetirementStatus.Confirmed` - the retirement status of the BatchNFT has ben confirmed
- `remainingSpace > quantity` - the quantity in Batch is not higher then total vintages
#### Output

 return this.onERC721Received.selector

#### Events
None
#### Function prototype

function onERC721Received(
        address, /* operator */
        address from,
        uint256 tokenId,
        bytes calldata /* data */
    ) external virtual override whenNotPaused returns (bytes4)

[*link to function*](https://github.com/CO2ken/contracts/blob/main/contracts/ToucanCarbonOffsets.sol#L122)

## Creating BCT tokens
WIP
## Retiring TCO2 tokens
WIP