17 units decimals

Overview

ERC-1155 uses integer balances, but carbon credits need decimal precision (e.g., 0.25 tons, 12,437.62 tons). This document explains how to handle decimals using fixed-point units.

The Challenge

ERC-1155 Limitation:

• Balances are uint256 (integers only)

• No native decimal support

Carbon Credit Requirements:

• Retail: 0.01, 0.25, 1.0 tons

• Enterprise: 12,437.62 tons (exact decimals)

• No rounding losses

Solution: Fixed-Point Units

Concept

Define a UNIT constant that represents 1 ton CO₂. All on-chain values are stored as multiples of UNIT.

Definition:

uint256 public constant UNIT = 1e6; // 1,000,000
// Or for maximum precision:
uint256 public constant UNIT = 1e18; // 1,000,000,000,000,000,000

Conversion:

1 ton CO₂ = 1 * UNIT
0.25 ton = 0.25 * UNIT = 250,000 (if UNIT = 1e6)
12,437.62 tons = 12,437.62 * UNIT = 12,437,620,000 (if UNIT = 1e6)

---

UNIT Selection

Option 1: UNIT = 1e6 (Recommended)

Precision: 6 decimal places (0.000001 tons)

Advantages:

• ✅ Sufficient precision for carbon credits

• ✅ Lower gas costs (smaller numbers)

• ✅ Easier to read in explorers

• ✅ Standard for many DeFi protocols

Example:

0.25 tons = 250,000 units
12,437.62 tons = 12,437,620,000 units

---

Option 2: UNIT = 1e18 (Maximum Precision)

Precision: 18 decimal places (0.000000000000000001 tons)

Advantages:

• ✅ Maximum precision

• ✅ Compatible with ERC-20 standard (wei-like)

• ✅ Future-proof for any precision needs

Disadvantages:

• ❌ Higher gas costs

• ❌ Harder to read in explorers

• ❌ Overkill for carbon credits

Example:

0.25 tons = 250,000,000,000,000,000 units
12,437.62 tons = 12,437,620,000,000,000,000,000 units

Recommendation: Use UNIT = 1e6 for carbon credits (sufficient precision, better gas efficiency).

---

Implementation

Contract Definition

contract CarbonCredit1155 {
    uint256 public constant UNIT = 1e6; // 1 ton = 1,000,000 units
    
    // All amounts in contract are in UNIT scale
    mapping(uint256 => uint256) public cap; // Cap in units
    mapping(uint256 => uint256) public issued; // Issued in units
    mapping(uint256 => uint256) public retired; // Retired in units
}

---

Conversion Functions

To On-Chain (Tons → Units)

function tonsToUnits(uint256 tons) public pure returns (uint256) {
    // For UNIT = 1e6, multiply by 1e6
    // For UNIT = 1e18, multiply by 1e18
    return tons * UNIT;
}

// Example: tonsToUnits(0.25) = 250000 (if UNIT = 1e6)

JavaScript/TypeScript:

const UNIT = 1e6;
function tonsToUnits(tons) {
    return Math.floor(tons * UNIT);
}
// tonsToUnits(0.25) = 250000
// tonsToUnits(12.43762) = 12437620

Note: Handle decimal input carefully. For exact decimals:

function tonsToUnits(tons) {
    // Convert to string, split by decimal point
    const [whole, decimal = ''] = tons.toString().split('.');
    const paddedDecimal = decimal.padEnd(6, '0').slice(0, 6);
    return parseInt(whole) * UNIT + parseInt(paddedDecimal);
}

---

From On-Chain (Units → Tons)

function unitsToTons(uint256 units) public pure returns (uint256) {
    // For UNIT = 1e6, divide by 1e6
    // For UNIT = 1e18, divide by 1e18
    return units / UNIT;
}

// Example: unitsToTons(250000) = 0 (integer division)
// Use view function that returns decimal representation

JavaScript/TypeScript:

const UNIT = 1e6;
function unitsToTons(units) {
    return units / UNIT;
}
// unitsToTons(250000) = 0.25
// unitsToTons(12437620) = 12.43762

---

UI Display

Display Balance:

// On-chain balance: 250000 (units)
const balanceUnits = 250000;
const balanceTons = balanceUnits / UNIT; // 0.25
displayAmount = balanceTons.toFixed(2); // "0.25"

Input to On-Chain:

// User enters: 0.25 tons
const userInput = "0.25";
const amountUnits = tonsToUnits(parseFloat(userInput)); // 250000
// Send amountUnits to contract

---

Example: Complete Flow

Project Setup

// Project cap: 10,000 tons
uint256 capTons = 10000;
uint256 capUnits = capTons * UNIT; // 10,000,000,000 (if UNIT = 1e6)

carbonCredit1155.setProjectConfig(
    projectTokenId,
    capUnits,  // Store as units
    ...
);

Credit Issuance

// Issue 2,000 tons
uint256 issueTons = 2000;
uint256 issueUnits = issueTons * UNIT; // 2,000,000,000

carbonCredit1155.mintCredits(
    projectTokenId,
    treasury,
    issueUnits  // Mint as units
);

Retail Purchase

// User buys 0.25 tons
const purchaseTons = 0.25;
const purchaseUnits = tonsToUnits(purchaseTons); // 250000

// On-chain: transfer 250000 units
await contract.transfer(user, projectTokenId, purchaseUnits);

// Display: 250000 / UNIT = 0.25 tons
const displayTons = purchaseUnits / UNIT; // 0.25

Enterprise Purchase

// Enterprise buys 12,437.62 tons (exact)
const purchaseTons = 12.43762;
const purchaseUnits = tonsToUnits(purchaseTons); // 12437620

// On-chain: transfer 12437620 units
await contract.transfer(enterprise, projectTokenId, purchaseUnits);

// Display: 12437620 / UNIT = 12.43762 tons
const displayTons = purchaseUnits / UNIT; // 12.43762

Retirement

// User retires 0.25 tons
uint256 retireTons = 0.25;
uint256 retireUnits = retireTons * UNIT; // 250000

carbonCredit1155.retire(projectTokenId, retireUnits);

---

Precision Considerations

Rounding

Always Round Down (for safety):

function tonsToUnits(tons) {
    return Math.floor(tons * UNIT);
}

Display Rounding:

function unitsToTons(units) {
    return Math.round((units / UNIT) * 100) / 100; // Round to 2 decimals
}

Maximum Values

With UNIT = 1e6:

• Maximum tons: 2^256 / 1e6 ≈ 1.15e71 tons (practically unlimited)

• Minimum precision: 0.000001 tons

With UNIT = 1e18:

• Maximum tons: 2^256 / 1e18 ≈ 1.15e59 tons (practically unlimited)

• Minimum precision: 0.000000000000000001 tons

---

Common Patterns

Check Balance

uint256 balanceUnits = carbonCredit1155.balanceOf(user, projectTokenId);
// balanceUnits is in UNIT scale

UI Display:

const balanceUnits = await contract.balanceOf(user, projectTokenId);
const balanceTons = balanceUnits / UNIT;
console.log(`Balance: ${balanceTons} tons`);

Validate Purchase Amount

const purchaseTons = 0.25;
const purchaseUnits = tonsToUnits(purchaseTons);
const availableUnits = await contract.getAvailableUnits(projectTokenId);

if (purchaseUnits > availableUnits) {
    throw new Error("Insufficient availability");
}

Calculate Total Price

const pricePerTon = 25.50; // USD
const purchaseTons = 0.25;
const purchaseUnits = tonsToUnits(purchaseTons);
const totalPrice = purchaseTons * pricePerTon; // 6.375 USD

---

Best Practices

1

Consistent UNIT Usage

• Define UNIT as a constant

• Use UNIT in all conversions

• Document UNIT value clearly

2

Input Validation

• Validate user input before conversion

• Check for overflow

• Handle decimal precision correctly

3

Display Formatting

• Always convert units to tons for display

• Use appropriate decimal places (2-6 for carbon credits)

• Show units in tooltips (optional)

4

Error Handling

• Handle conversion errors gracefully

• Validate amounts before on-chain calls

• Provide clear error messages