16 token id strategy

Overview

The token ID strategy is critical for the semi-fungible credit system. It determines how projects map to credit token IDs and affects traceability, scalability, and operational complexity.

Strategy Options

Option 1: tokenId = ProjectRecordId (Recommended for v1)

Mapping:

ProjectRecord tokenId = 101
Credit Units tokenId = 101

Implementation:

// When ProjectRecord is minted
uint256 projectTokenId = projectRegistry.mintProjectRecord(...);

// Credits use the same tokenId
carbonCredit1155.setProjectConfig(projectTokenId, capUnits, ...);
carbonCredit1155.mintCredits(projectTokenId, to, amountUnits);

Advantages:

• ✅ Easiest to trace and reason about

• ✅ Direct 1:1 mapping

• ✅ Simple implementation

• ✅ Clear project-to-credits relationship

Disadvantages:

• ❌ One project = one issuance batch

• ❌ Cannot issue multiple batches per project easily

Use Case: One project record represents one issuance batch (most common for v1).

Option 2: tokenId = hash(projectId + vintage + verifier + methodology)

Mapping:

Project A 2024 → tokenId = keccak256("PROJ-A" + "2024" + "Verra" + "VCS")
Project A 2025 → tokenId = keccak256("PROJ-A" + "2025" + "Verra" + "VCS")

Implementation:

function generateTokenId(
    string memory projectId,
    uint256 vintageYear,
    string memory verifier,
    string memory methodology
) public pure returns (uint256) {
    return uint256(keccak256(abi.encodePacked(
        projectId,
        vintageYear,
        verifier,
        methodology
    )));
}

Advantages:

• ✅ Supports multiple batches per project

• ✅ Batch-specific tracking

• ✅ Flexible issuance model

Disadvantages:

• ❌ More complex tokenId generation

• ❌ Requires batch management

• ❌ Harder to trace without mapping table

Use Case: Multiple issuance batches per project (common in carbon markets).

Option 3: Sequential Token IDs with Mapping

Mapping:

ProjectRecord tokenId = 101
Credit Batch 1 tokenId = 1001 (mapped to project 101)
Credit Batch 2 tokenId = 1002 (mapped to project 101)

Implementation:

mapping(uint256 => uint256) public creditTokenIdToProjectId;
mapping(uint256 => uint256[]) public projectIdToCreditTokenIds;

function createCreditBatch(
    uint256 projectTokenId,
    uint256 capUnits
) external returns (uint256 creditTokenId) {
    creditTokenId = nextCreditTokenId++;
    creditTokenIdToProjectId[creditTokenId] = projectTokenId;
    projectIdToCreditTokenIds[projectTokenId].push(creditTokenId);
    // ... configure credit batch
}

Advantages:

• ✅ Clear batch separation

• ✅ Multiple batches per project

• ✅ Sequential IDs (easier to iterate)

Disadvantages:

• ❌ Requires mapping tables

• ❌ More complex queries

• ❌ Additional gas costs

Use Case: Complex multi-batch scenarios.

Recommendation

For v1: Use Option 1

Rationale:

• Simplest implementation

• Easiest to understand and audit

• Sufficient for most use cases

• Can upgrade to Option 2 later if needed

For Future: Consider Option 2

When to Upgrade:

• Need multiple issuance batches per project

• Different vintages need separate tracking

• Different verifiers/methodologies per project

Implementation Example (Option 1)

ProjectRegistry

contract ProjectRegistry {
    uint256 public nextProjectId = 1;
    mapping(uint256 => ProjectRecord) public projectRecords;
    
    function mintProjectRecord(...) external returns (uint256 projectTokenId) {
        projectTokenId = nextProjectId++;
        projectRecords[projectTokenId] = ProjectRecord(...);
        _mint(to, projectTokenId);
        return projectTokenId;
    }
}

CarbonCredit1155

contract CarbonCredit1155 {
    IProjectRegistry public projectRegistry;
    
    function setProjectConfig(
        uint256 projectTokenId,  // Same as ProjectRecord tokenId
        uint256 capUnits,
        TransferPolicy policy,
        bool active
    ) external {
        require(
            projectRegistry.ownerOf(projectTokenId) != address(0),
            "ProjectRecord does not exist"
        );
        // ... set config using projectTokenId as tokenId
    }
    
    function mintCredits(
        uint256 projectTokenId,  // Same as ProjectRecord tokenId
        address to,
        uint256 amountUnits
    ) external {
        // ... mint using projectTokenId as tokenId
        _mint(to, projectTokenId, amountUnits, "");
    }
}

Usage

1

Mint ProjectRecord

uint256 projectTokenId = projectRegistry.mintProjectRecord(...);
// projectTokenId = 101

2

Configure credits (same tokenId)

carbonCredit1155.setProjectConfig(101, capUnits, ...);

3

Mint credits (same tokenId)

carbonCredit1155.mintCredits(101, treasury, amountUnits);

4

User holds credits (same tokenId)

uint256 balance = carbonCredit1155.balanceOf(user, 101);

Token ID Lookup Patterns

Query Credits by Project

// With Option 1: Direct
uint256 projectTokenId = 101;
uint256 balance = carbonCredit1155.balanceOf(user, projectTokenId);

// With Option 2: Need mapping
uint256[] memory creditTokenIds = projectIdToCreditTokenIds[projectId];
for (uint i = 0; i < creditTokenIds.length; i++) {
    balance += carbonCredit1155.balanceOf(user, creditTokenIds[i]);
}

Query Project by Credit TokenId

// With Option 1: Direct (same ID)
uint256 projectTokenId = creditTokenId;

// With Option 2: Need mapping
uint256 projectTokenId = creditTokenIdToProjectId[creditTokenId];

Migration Considerations

From Option 1 to Option 2

1

Create Mapping Table

mapping(uint256 => uint256) public creditTokenIdToProjectId;

2

Migrate Existing Credits

• Keep existing tokenIds

• Add mapping entries

• New batches use new tokenIds

3

Update Queries

• Update balance queries to use mapping

• Update project queries to aggregate batches

Best Practices

1

Consistent Naming

• Use projectTokenId consistently

• Clarify when tokenId refers to ProjectRecord vs Credit

2

Validation

• Always validate ProjectRecord exists before configuring credits

• Check tokenId ownership/validity

3

Documentation

• Document tokenId strategy clearly

• Provide examples for developers

4

Future-Proofing

• Design contracts to support migration

• Consider upgrade paths