CarbonMarketplace

Inherits: AccessControl, ReentrancyGuard, Pausable. Uses SafeERC20 for the payment token.

Constructor

constructor(address paymentToken_, address carbonToken_, address nftContract_)

All three must be non-zero (Invalid payment token, Invalid carbon token, Invalid NFT contract) and are immutable: paymentToken, carbonToken (a single CarbonCreditToken), nftContract (stored, unused by marketplace functions). The constructor:

• reads decimals() of the payment token and requires 2 <= decimals <= 18 (Unsupported payment decimals); it is stored as the immutable paymentDecimals;
• requires the carbon token to have exactly 18 decimals (Carbon token must have 18 decimals);
• grants the deployer DEFAULT_ADMIN_ROLE, MATCHER_ROLE, KYC_ROLE, PAUSER_ROLE and FEE_MANAGER_ROLE;
• sets minPricePerTonne to 10**(decimals-2) (0.01 USD per tonne, 10_000 for 6-decimal payment token).

On mainnet the payment token is the real payment token; on testnet it is a mock.

Units, prices and fees

Fees: the fee rate is snapshotted when an order or auction is created (orderFeeBps(orderId), auctionFeeBps(auctionId)), so later setTradingFee calls are not retroactive. Order-book and auction fees are deducted from what the seller or taker receives and are tracked in accruedFees; the fee manager sweeps them with withdrawFees. The fee is always paid by the CCT seller and may be reduced by the fee discount of that party. AMM swap fees are not tracked there: they stay in the pool reserves and accrue to liquidity providers, and are never discounted.

Roles

The four parameter setters use the onlyParameterAdmin modifier: the caller must hold PARAMETER_ROLE, or else DEFAULT_ADMIN_ROLE. All roles are OpenZeppelin AccessControl roles and can be granted to a multisig with grantRole, after which the deployer should renounceRole.

Fee discount

The marketplace can read an optional fee-discount provider (feeDiscountProvider, address(0) = off) that implements IFeeDiscount.discountBps(user). CarbStaking is such a provider: its tier is the discount, see CarbStaking. The discount applies to the trading fee, never to the price.

The 60,000-gas call follows the EIP-150 63/64 rule: a transaction sent with barely enough gas could run out of gas after a failed provider call, so use normal gas estimation.

Order book

struct Order {
    uint256 orderId; address trader; bool isBuyOrder;
    uint256 amount; uint256 pricePerTonne; uint256 filled;
    bool isActive; uint256 createdAt; uint256 expiresAt; bool requiresKYC;
}

createBuyOrder, createSellOrder, fillOrder are whenNotPaused and nonReentrant.

fillOrder, with cost = amount * pricePerTonne / 1e18 and fee = cost * orderFeeBps / 10000:

When filled == amount the order is deactivated. Emits OrderFilled(orderId, taker, amountFilled, totalCost). Anyone fills orders directly; orders are not matched against each other.

Auctions

struct Auction {
    uint256 auctionId; address seller; uint256 amount;
    uint256 startPrice; uint256 highestBid; address highestBidder;
    uint256 startTime; uint256 endTime; bool isActive;
}

Constants: MIN_AUCTION_DURATION = 1 hour (3600), MAX_AUCTION_DURATION = 30 days. Events: AuctionCreated, BidPlaced, AuctionFinalized(auctionId, winner, winningBid) (winner address(0), bid 0 when unsold), AuctionCancelled.

Pull payments: claim()

Outbid refunds, auction seller proceeds and sell-order maker proceeds are pushed to the recipient directly. If the payment token refuses the transfer (for example a payment token blacklist), the amount is credited to pendingWithdrawals[address] and PaymentDeferred(to, amount) is emitted, so one failing recipient cannot block settlement for everyone else.

AMM pool

struct Pool { uint256 carbonReserve; uint256 stableReserve; uint256 totalLPTokens; uint256 lastPrice; uint256 lastUpdate; }

A single pool (ammPool) for the CCT / payment-token pair. LP shares are an internal mapping lpTokens, not an ERC-20. The AMM functions exist onchain but are not wired into the web app UI.

Swap math: fee = amountIn * tradingFeePercent / 10000; out = inAfterFee * reserveOut / (reserveIn + inAfterFee). The full amountIn (fee included) is added to the reserve, so the fee accrues to LPs. lastPrice is set to stableReserve * 1e18 / carbonReserve. Emits Swap(trader, carbonToStable, amountIn, amountOut, fee). getPrice() returns the same spot price (0 if the pool is empty). There is no deadline parameter.

KYC

KYC is an onchain whitelist flag (kycVerified) set by KYC_ROLE; no external provider is integrated.

• Order book (opt-in): an order created with requiresKYC_ = true needs a KYC'd creator. At fill time the taker must be KYC'd and the maker is re-checked (Maker KYC revoked). Makers can always cancel.
• AMM and auctions: non-KYC by default. The admin can call setKYCGate(true); then addLiquidity, swap, createAuction and placeBid revert KYC required. Exits (removeLiquidity, cancelOrder, cancelAuction, finalizeAuction, claim) are never gated.
• KYC does not follow the CCT ERC-20 once it is transferred (a documented limitation).

Views

getPrice(), quoteAddLiquidity, getOrder(id), getAuction(id), getUserOrders(user), getUserAuctions(user), and the public getters orders, auctions, kycVerified, kycGateEnabled, lpTokens, userOrders, userAuctions, ammPool, nextOrderId, nextAuctionId, tradingFeePercent, accruedFees, pendingWithdrawals, orderFeeBps, auctionFeeBps, minPricePerTonne, MAX_MIN_PRICE_PER_TONNE, DEFAULT_MIN_PRICE_PER_TONNE, MAX_PRICE_PER_TONNE, paymentToken, paymentDecimals, carbonToken, nftContract, MINIMUM_LIQUIDITY, MIN_AUCTION_DURATION, MAX_AUCTION_DURATION, MAX_TRADING_FEE, FEE_DENOMINATOR, CARBON_UNIT. Ids start at 1.

Fee-discount reads: feeDiscountProvider, feeDiscountBpsOf(user), MAX_FEE_DISCOUNT_BPS, DISCOUNT_GAS_LIMIT.

Admin

Events

Approvals required by callers

Approvals in the web app are exact bigint amounts (payment token cost rounded up). The allowance is re-read before each transaction and re-approved when short.

Notes

• CCT transfers use plain transferFrom/transfer (not SafeERC20); the OpenZeppelin CCT reverts on failure, so this is safe for this token.
• Buy-order cancellation refunds unfilled * price / 1e18, recomputed from the unfilled amount, which can differ from escrow by rounding dust when partially filled.
• Orders store requiresKYC at creation; expiresAt = type(uint256).max when no expiry is set.
• The minimum and maximum price are enforced on the order book and auctions. addLiquidity and swap have no price input (the price is derived from pool reserves).