CarbonLedger Smart Contracts

Production-ready Soroban smart contracts for the CarbonLedger decentralized carbon credit marketplace on Stellar.

Overview

CarbonLedger enables carbon offset developers to mint tokenized carbon credits as Real World Assets (RWAs) on-chain after third-party verification. Corporations and individuals can purchase these credits using USDC/XLM and permanently retire (burn) them to claim offset credits. The retirement process is irreversibly recorded on-chain, preventing double-counting or re-selling of retired credits.

Tagline: "Tokenize, trade, and retire carbon credits with absolute provenance on Stellar."

Contract Architecture

1. Carbon Registry (`carbon_registry`)

Manages project registration, verification, and lifecycle.

Key Functions:

initialize() - Initialize the registry with admin and verifier addresses
register_project() - Register a new carbon offset project (developer-initiated)
verify_project() - Verify project authenticity (verifier-only)
suspend_project() - Suspend fraudulent projects (admin-only)
get_project() - Retrieve project metadata
get_project_status() - Check project verification status

Data Model:

CarbonProject: Contains project ID, developer address, name, location, standard, credit ticker, supply tracking, and verification status
ProjectStatus: Enum for AwaitingVerification, Verified, Suspended

Security Features:

Authorization guards on all state-changing functions
Comprehensive error handling (15+ error types)
Immutable project records once registered

2. Carbon Credit (`carbon_credit`)

Handles credit minting, trading, and irreversible retirement.

Key Functions:

initialize() - Initialize with admin and USDC token address
mint_credits() - Mint verified carbon credits to developer balance
transfer_credits() - Transfer credits between addresses
buy_credits() - Atomic purchase: USDC → developer, credits → buyer
retire_credits() - Irreversibly burn credits and record retirement
get_balance() - Check tradeable credit balance for an address
get_retirement_record() - Retrieve permanent retirement certificate

Data Model:

CreditBatch: Represents a minting batch with metadata and supply tracking
RetirementCertificate: Immutable record of retired credits (benefactor, amount, timestamp)
CreditStatus: Enum for Active, Retired, Suspended

Production Safety Features:

✅ Checked Arithmetic: All operations use checked_add(), checked_mul() for overflow detection
✅ Irreversibility Guarantee: No reversal logic; retired credits permanently removed
✅ Atomic Transactions: USDC transfers paired with credit transfers (no partial operations)
✅ Serial Number Tracking: Each credit batch has unique serial to prevent duplicate retirement
✅ Comprehensive Logging: All state-changing operations logged for auditability

3. Carbon Marketplace (`carbon_marketplace`)

Manages peer-to-peer trading of carbon credits with price discovery.

Key Functions:

initialize() - Initialize with admin and USDC token address
create_listing() - Seller creates an ask order (credits + price)
cancel_listing() - Seller cancels an active listing
buy_listing() - Buyer executes a purchase (atomic USDC + credits swap)
get_listing() - Retrieve active marketplace listings
get_listing_history() - Query historical trades

Data Model:

MarketListing: Tracks seller, credits, price, status, and timestamp
ListingStatus: Enum for Active, Filled, Cancelled

Key Features:

Decentralized price discovery through peer listings
Atomic marketplace swaps (no escrow risk)
Full audit trail of trades

4. Carbon Oracle (`carbon_oracle`)

Monitoring data and benchmark pricing for credits.

Key Functions:

initialize() - Initialize with admin and oracle provider address
submit_monitoring_data() - Oracle submits real-world monitoring (satellite/sensor data)
submit_price() - Oracle submits benchmark pricing
flag_project() - Oracle flags suspicious projects
get_monitoring_data() - Retrieve monitoring records
get_current_price() - Get latest benchmark price

Data Model:

MonitoringData: Stores monitoring type, payload, timestamp, and data source
Supports: satellite monitoring, sensor data, verification updates, price benchmarks

Key Features:

Off-chain monitoring data recorded on-chain for verification
Decentralized price oracles (multiple data sources supported)
Project flagging mechanism for suspected fraud

Building & Testing

Prerequisites

Rust: Latest stable version
Soroban CLI: cargo install soroban-cli@latest
wasm32 target: rustup target add wasm32-unknown-unknown

Local Build

# Build all contracts
cargo build --release --target wasm32-unknown-unknown

# Build individual contract
cargo build --release --target wasm32-unknown-unknown -p carbon-credit

Testing

# Run all tests
cargo test --release

# Run specific contract tests
cargo test --release -p carbon-credit

# Run with logging
RUST_LOG=debug cargo test --release -- --nocapture

Optimization

Compiled .wasm files are located in target/wasm32-unknown-unknown/release/:

ls -lh target/wasm32-unknown-unknown/release/*.wasm

Expected sizes:

carbon_registry.wasm: ~120 KB
carbon_credit.wasm: ~150 KB
carbon_marketplace.wasm: ~140 KB
carbon_oracle.wasm: ~130 KB

Deployment

Testnet Deployment

# Set environment variables
export SOROBAN_RPC_HOST=https://soroban-testnet.stellar.org
export SOROBAN_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"

# Deploy carbon registry (step 1 - foundational)
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/carbon_registry.wasm \
  --source <source_account>

# Deploy other contracts similarly
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/carbon_credit.wasm \
  --source <source_account>

Mainnet Deployment

export SOROBAN_RPC_HOST=https://soroban-mainnet.stellar.org
export SOROBAN_NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015"

# Deploy with multi-sig approval for production safety
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/carbon_registry.wasm \
  --source <multisig_account>

Contract Interaction Examples

Register & Verify a Project

# 1. Developer registers project
soroban contract invoke \
  --id <REGISTRY_CONTRACT_ID> \
  --source <developer_account> \
  -- register_project \
  --name "Amazon Reforestation 2026" \
  --location "Amazonas, Brazil" \
  --standard "Verra" \
  --credit_ticker "CO2-AMZ-2026" \
  --price_per_ton 25000000 # 25 USDC stroops

# 2. Verifier verifies the project
soroban contract invoke \
  --id <REGISTRY_CONTRACT_ID> \
  --source <verifier_account> \
  -- verify_project \
  --project_id 1

Mint & Purchase Credits

# 1. Developer mints 1,000 credits for verified project
soroban contract invoke \
  --id <CREDIT_CONTRACT_ID> \
  --source <developer_account> \
  -- mint_credits \
  --project_id 1 \
  --amount 1000

# 2. Corporate buyer purchases 100 credits
soroban contract invoke \
  --id <CREDIT_CONTRACT_ID> \
  --source <buyer_account> \
  -- buy_credits \
  --project_id 1 \
  --amount 100 \
  --price_per_ton 25000000

Retire Credits (Irreversible)

# Buyer permanently retires 50 credits to offset their carbon footprint
soroban contract invoke \
  --id <CREDIT_CONTRACT_ID> \
  --source <buyer_account> \
  -- retire_credits \
  --project_id 1 \
  --amount 50 \
  --benefactor "Acme Corp Carbon Offset"

# Retrieve retirement certificate
soroban contract invoke \
  --id <CREDIT_CONTRACT_ID> \
  -- get_retirement_record \
  --project_id 1 \
  --benefactor "<buyer_address>"

Error Handling

All contracts implement comprehensive error handling:

Common Error Types

Unauthorized: Caller lacks required permissions
InvalidProjectId: Project does not exist
ProjectNotVerified: Attempted operation on unverified project
InsufficientBalance: Not enough credits to perform operation
InvalidAmount: Amount is zero or exceeds supply
OverflowError: Arithmetic overflow detected
InvalidStatus: Attempted operation on invalid project/credit status
AlreadyRetired: Attempted to re-retire credits
TransferFailed: USDC transfer failed
ContractAlreadyInitialized: Contract initialization called twice

Security Considerations

Audit Trail & Immutability

All retirement operations create permanent, immutable RetirementCertificate records
No mechanism exists to revert retired credits (by design)
All state transitions logged for compliance and forensic analysis

Overflow Protection

// All arithmetic operations use checked operations:
let new_balance = balance.checked_add(amount)?;  // Overflow safe
let total_cost = price.checked_mul(quantity)?;   // Multiplication safe

Authorization

// All state-changing functions require authorization:
buyer.require_auth();
developer.require_auth();
admin.require_auth();

Atomicity

// Marketplace purchases are atomic:
// - USDC transfer happens
// - Credits transfer happens
// - Both succeed or both fail (no partial state)

Testing Strategy

Unit Tests (Per-Contract)

✅ Project registration and verification workflow
✅ Credit minting and balance tracking
✅ Buy/sell operations with USDC transfers
✅ Irreversible retirement and certificate generation
✅ Overflow detection on arithmetic operations
✅ Authorization guard enforcement

Integration Tests (Cross-Contract)

✅ Registry → Credit workflow (register, verify, mint, buy)
✅ Credit → Marketplace workflow (list, purchase, retire)
✅ Oracle → Registry feedback loop (monitoring, pricing, flagging)

Fuzzing & Property Tests

Test all arithmetic operations with extreme values
Verify retirement records are immutable
Confirm USDC transfers are atomic with credit transfers

Development Workflow

Code Organization

carbon_registry/
├── Cargo.toml          # Dependencies & metadata
└── src/
    └── lib.rs          # All contract logic (~400 lines)

carbon_credit/
├── Cargo.toml
└── src/
    └── lib.rs          # Credit management (~500 lines)

carbon_marketplace/
├── Cargo.toml
└── src/
    └── lib.rs          # Marketplace logic (~450 lines)

carbon_oracle/
├── Cargo.toml
└── src/
    └── lib.rs          # Oracle data (~350 lines)

Version Management

Soroban SDK: v21.5.0 (latest stable)
Rust Edition: 2021
WASM Target: wasm32-unknown-unknown

Contributing

Code Standards

✅ Zero panics in production code (use Result types)
✅ Comprehensive error handling with custom error types
✅ Checked arithmetic on all operations
✅ Authorization guards on all state mutations
✅ Logging for all critical operations

Pull Request Process

Fork the repository
Create a feature branch: git checkout -b feat/new-feature
Make changes and add tests
Build & test: cargo test --release
Create PR with description of changes
Address code review feedback
Merge after approval

Deployment Checklist

All tests pass: cargo test --release
Build succeeds: cargo build --release --target wasm32-unknown-unknown
WASM files generated and verified
Security audit completed
Contract initialization parameters validated
Testnet deployment successful
Monitoring and alerting configured
Mainnet deployment approved by governance
Post-deployment verification on testnet

Support & Resources

Soroban Documentation: https://developers.stellar.org/
Stellar Development Discord: https://discord.gg/stellardev
CarbonLedger GitHub: https://github.com/Carbon-Ledger-stellar/
Verra Methodology: https://verra.org/
Gold Standard: https://www.goldstandard.org/

License

All code in this repository is licensed under the Apache 2.0 License. See LICENSE file for details.

Changelog

v1.0.0 (Production Release)

✅ Carbon Registry contract: Project registration & verification
✅ Carbon Credit contract: Credit minting, trading, retirement
✅ Carbon Marketplace contract: P2P credit trading
✅ Carbon Oracle contract: Monitoring data & pricing
✅ Comprehensive error handling (40+ error types across contracts)
✅ Checked arithmetic on all operations
✅ Immutable retirement records (no reversal mechanism)
✅ Full test suite with 50+ test cases
✅ Production deployment guide

Contract Status

Contract	Status	Tests	Audit	Deployment
Carbon Registry	✅ Production	✅ Pass	✅ Approved	Ready
Carbon Credit	✅ Production	✅ Pass	✅ Approved	Ready
Carbon Marketplace	✅ Production	✅ Pass	✅ Approved	Ready
Carbon Oracle	✅ Production	✅ Pass	✅ Approved	Ready

Last Updated: July 14, 2026
Maintained By: CarbonLedger Development Team

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github/workflows		.github/workflows
carbon_credit		carbon_credit
carbon_marketplace		carbon_marketplace
carbon_oracle		carbon_oracle
carbon_registry		carbon_registry
.gitignore		.gitignore
Cargo.toml		Cargo.toml
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

CarbonLedger Smart Contracts

Overview

Contract Architecture

1. Carbon Registry (carbon_registry)

2. Carbon Credit (carbon_credit)

3. Carbon Marketplace (carbon_marketplace)

4. Carbon Oracle (carbon_oracle)

Building & Testing

Prerequisites

Local Build

Testing

Optimization

Deployment

Testnet Deployment

Mainnet Deployment

Contract Interaction Examples

Register & Verify a Project

Mint & Purchase Credits

Retire Credits (Irreversible)

Error Handling

Common Error Types

Security Considerations

Audit Trail & Immutability

Overflow Protection

Authorization

Atomicity

Testing Strategy

Unit Tests (Per-Contract)

Integration Tests (Cross-Contract)

Fuzzing & Property Tests

Development Workflow

Code Organization

Version Management

Contributing

Code Standards

Pull Request Process

Deployment Checklist

Support & Resources

License

Changelog

v1.0.0 (Production Release)

Contract Status

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

1. Carbon Registry (`carbon_registry`)

2. Carbon Credit (`carbon_credit`)

3. Carbon Marketplace (`carbon_marketplace`)

4. Carbon Oracle (`carbon_oracle`)