Transparent, tamper-proof carbon credit registry and marketplace built on the Stellar network.

CarbonChain is a Soroban-native platform for issuing, trading, and retiring tokenized carbon credits. It enables smart contracts to enforce real-world climate accountability — verifier multi-sig, MRV oracle integration, and permanent on-chain retirement receipts — in a trust-minimized way.

• Credit issuance with verifier multi-sig approval
• Permanent on-chain retirement with tamper-proof certificates
• On-chain offer-book marketplace for secondary market trading (Stellar DEX AMM integration is a Phase 3 roadmap item)
• MRV oracle interface for real-time carbon sequestration monitoring
• IPFS-anchored project documentation (methodology, satellite imagery, audits)
• Session-based audit trail for all credit lifecycle operations
• Replay attack protection on all contract state transitions
• Fractional credits (0.1 tonne resolution via i128 storage)
  • Unit convention: 1 tonne = 1,000,000 units, minimum unit = 100,000 (= 0.1 tonne)
  • All tonnes values must be a positive multiple of 100,000; non-multiples are rejected
• Anchor info discovery for SEP-10 authenticated interactions
• Health monitoring for registered verifier nodes
• Event emission for all state changes
• Comprehensive error handling with stable error codes

Projects can register credits across the following methodologies:

• REDD+ — Reduced Emissions from Deforestation and Degradation
• VCS — Verified Carbon Standard (Verra)
• Gold Standard — Gold Standard for the Global Goals
• CDM — Clean Development Mechanism
• Plan Vivo — Community and ecosystem-based projects
• Custom — Configurable methodology string for emerging standards

// Initialize the registry contract
contract.initialize(&admin);

// Register a verifier
contract.register_verifier(&verifier);

// Verifier self-configures their own service capabilities
// (verifier signs with their own key — this is NOT an admin operation)
let nonce = contract.get_nonce(&verifier);
let mut capabilities = Vec::new(&env);
capabilities.push_back(ServiceType::CreditApproval);
capabilities.push_back(ServiceType::MRVReview);
contract.configure_verifier_services(&verifier, &capabilities, nonce);

// Submit a credit for approval
let credit_id = contract.submit_credit(
    &issuer,
    &CreditMetadata {
        project_id: String::from_str(&env, "PROJ-001"),
        vintage_year: 2024,
        methodology: String::from_str(&env, "VCS"),
        geography: String::from_str(&env, "NG"),
        tonnes: 1_000_000,   // 1 tonne (1 tonne = 1_000_000 units, i.e. TONNES_SCALE)
        ipfs_hash: String::from_str(&env, "bafybei..."),
    },
);

// Verifier approves and triggers mint
// (requires ServiceType::CreditApproval in configured services,
//  or no services configured — open-capability assumption)
contract.approve_and_mint(&verifier, &credit_id);

// Retire a credit
contract.retire(&buyer, &credit_id, &String::from_str(&env, "2024 Scope 3 offset"));

See the complete issuance, trading, and retirement workflow:

# Run bash demo
./examples/cli_example.sh

# Or run Rust example
cargo run --example cli_example

See docs/guides/DOCTOR_COMMAND.md for CLI environment diagnostics.

• Credit Registry: Register projects, submit credits, enforce verifier approval before minting
• Retirement Engine: Permanently burn tokens with an immutable on-chain retirement record
• Marketplace: On-chain offer-book listings with fractional credit support (Stellar DEX AMM integration is a Phase 3 roadmap item)
• MRV Oracle: Authenticated data ingestion from IoT/satellite feeds with anomaly flagging
• Session Traceability: Group operations into auditable sessions for compliance
• Audit Trail: Immutable record of all lifecycle events
• Replay Protection: Nonce-based multi-level protection on all contract operations
• Credential Security: Admin keypair never exposed to frontend — all user ops signed via Freighter

CarbonChain includes comprehensive session management and operation tracing to ensure all credit interactions are reproducible and auditable.

What this means:

• Every operation is logged with complete context (who, what, when, result)
• Sessions group related operations for logical organization
• Audit trail is immutable for compliance and verification
• Operations can be replayed deterministically for dispute resolution
• Replay attacks are prevented through nonce-based protection

Quick example:

// Create a session
const sessionId = await contract.create_session(userAddress);

// Submit attestation within session
const creditId = await contract.submit_credit_with_session(
    sessionId,
    issuer,
    metadata,
    ipfsHash,
    signature
);

// Verify session completeness
const opCount = await contract.get_session_operation_count(sessionId);

// Retrieve full audit log
const auditLog = await contract.get_audit_log(0);

carbonchain/
├── contracts/                  # Soroban smart contracts (Rust)
│   ├── credit_registry/        # Minting, metadata, verifier multi-sig
│   │   ├── src/
│   │   │   ├── lib.rs          # Contract entry points
│   │   │   ├── storage.rs      # Persistent data management
│   │   │   ├── events.rs       # Event definitions
│   │   │   ├── types.rs        # Data structures
│   │   │   └── errors.rs       # Stable error codes
│   │   └── Cargo.toml
│   ├── retirement/             # Burn + retirement certificate logic
│   ├── marketplace/            # Offer creation, on-chain offer book (DEX AMM is Phase 3)
│   └── mrv_oracle/             # Oracle interface for MRV data updates
│
├── api/                        # NestJS backend
│   ├── src/
│   │   ├── stellar/            # Stellar SDK service layer
│   │   ├── credits/            # Credit CRUD, issuance flow
│   │   ├── retirement/         # Retirement endpoint + certificate gen
│   │   ├── marketplace/        # Order book, DEX bridge (AMM is Phase 3)
│   │   ├── projects/           # Project profiles, IPFS uploads
│   │   ├── verifiers/          # Verifier registry, co-sign requests
│   │   └── oracle/             # MRV data ingestion webhooks
│   ├── test/
│   └── package.json
│
├── frontend/                   # Angular 17+ SPA
│   ├── src/app/
│   │   ├── core/               # Auth, wallet, HTTP services
│   │   ├── shared/             # Reusable components and pipes
│   │   ├── dashboard/          # Portfolio overview
│   │   ├── marketplace/        # Browse & buy credits
│   │   ├── projects/           # Project detail pages
│   │   ├── retire/             # Retirement wizard
│   │   ├── certificates/       # Retirement certificate viewer
│   │   └── admin/              # Verifier & maintainer panel
│   └── package.json
│
├── shared/                     # Shared TypeScript types & constants
├── scripts/                    # Deployment & testnet setup scripts
├── docs/
│   ├── README.md               # Full documentation index
│   ├── architecture.md         # System architecture (this repo)
│   ├── features/               # Feature-specific documentation
│   └── guides/                 # Developer guides
├── CLAUDE.md                   # Claude Code context file
├── CONTRIBUTING.md             # Contribution guide (Stellar Wave)
└── README.md

• Node.js 18+ and npm 9+
• Rust (stable toolchain) — rustup.rs
• Soroban CLI — cargo install --locked [email protected] --features opt
• Docker — for local PostgreSQL
• Freighter browser extension — freighter.app
• A Stellar testnet keypair — laboratory.stellar.org

git clone [email protected]:legend-esc/carbonchain.git
cd carbonchain

cp api/.env.example api/.env
# Fill in ADMIN_SECRET_KEY, JWT_SECRET, and contract IDs — see Environment Variables below

The docker-compose.yml starts all four services (PostgreSQL, Redis, API, Frontend) in the correct dependency order with health checks:

docker compose up -d

Check service health:

docker compose ps
docker compose logs -f api

cd api && npm run migration:run

If you prefer to run services individually:

# Start only the backing services
docker compose up -d postgres redis

# Install dependencies
cd api && npm install
cd ../frontend && npm install

# Terminal 1 — NestJS API (port 3000)
cd api && npm run start:dev

# Terminal 2 — Angular frontend (port 4200)
cd frontend && ng serve

Open http://localhost:4200 and connect your Freighter wallet on Stellar testnet.

cd scripts
./deploy-testnet.sh

This funds a testnet account, compiles all four Soroban contracts, deploys them, and writes the resulting contract IDs to scripts/contract-ids.testnet.json.

# Stellar
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_SOROBAN_RPC=https://soroban-testnet.stellar.org
ADMIN_SECRET_KEY=S...

# Contract IDs (populated after deploy-testnet.sh)
CREDIT_REGISTRY_CONTRACT_ID=C...
RETIREMENT_CONTRACT_ID=C...
MARKETPLACE_CONTRACT_ID=C...
MRV_ORACLE_CONTRACT_ID=C...

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/carbonchain

# Auth
JWT_SECRET=your-jwt-secret-here
JWT_EXPIRES_IN=7d

# IPFS
IPFS_API_URL=https://api.pinata.cloud
IPFS_API_KEY=your-pinata-api-key
IPFS_SECRET_KEY=your-pinata-secret

# Redis (#975 — password required; matches REDIS_PASSWORD in docker-compose.yml)
# Generate a strong secret for production: openssl rand -hex 32
REDIS_PASSWORD=changeme-local-dev
REDIS_URL=redis://:changeme-local-dev@localhost:6379

export const environment = {
  production: false,
  apiUrl: 'http://localhost:3000',
  stellarNetwork: 'testnet',
  horizonUrl: 'https://horizon-testnet.stellar.org',
};

All contracts live in contracts/ and are written in Rust targeting the Soroban SDK.

cd contracts
cargo build --target wasm32-unknown-unknown --release

See docs/features/ERROR_CODES_REFERENCE.md for the full error code reference.

Base URL: http://localhost:3000/api/v1

Swagger UI available at http://localhost:3000/api/docs in development.

Session Management

Session-Aware Operations

# Smart contract tests
cd contracts && cargo test

# Cross-platform path tests
cd contracts && cargo test cross_platform

# API unit + integration tests
cd api && npm run test
cd api && npm run test:e2e

# Frontend tests
cd frontend && ng test

Linux / macOS

./validate_all.sh
./pre_deploy_validate.sh

Windows

.\validate_all.ps1
.\pre_deploy_validate.ps1

anchorkit doctor

The doctor command checks:

• ✅ Rust toolchain installation
• ✅ WASM target availability
• ✅ Wallet configuration
• ✅ Soroban RPC connectivity
• ✅ Config file validity
• ✅ Network connectivity

See docs/guides/DOCTOR_COMMAND.md for complete documentation.

• QUICK_START.md — Quick reference with examples
• CONTRIBUTING.md — Contribution guidelines (Stellar Wave)
• CHANGELOG.md — Version history

• docs/features/ERROR_CODES_REFERENCE.md — Stable API error codes
• docs/features/SEP10_AUTH.md — SEP-10 Freighter authentication
• docs/features/ANCHOR_INFO_DISCOVERY.md — stellar.toml parsing and caching
• docs/features/METADATA_CACHE.md — TTL-based metadata caching
• docs/features/REQUEST_ID_PROPAGATION.md — UUID request tracing
• docs/features/RETRY_BACKOFF.md — Retry and backoff strategies
• docs/features/WEBHOOK_MONITOR.md — MRV oracle webhook monitoring
• docs/features/TRANSACTION_STATE_TRACKER.md — Credit lifecycle state machine
• docs/features/STATUS_MONITOR.md — Verifier node health monitoring
• docs/features/ROUTING_STRATEGY.md — DEX routing strategy
• docs/features/LOGGING.md — Logging system
• docs/features/DOMAIN_VALIDATION.md — Domain validation for anchors

• docs/guides/DOCTOR_COMMAND.md — CLI diagnostics
• docs/guides/CONTRIBUTING.md — Contribution guidelines
• docs/guides/ERROR_IMPLEMENTATION_GUIDE.md — Error handling guide
• docs/guides/RETRY_QUICK_REFERENCE.md — Retry patterns quick reference

See docs/README.md for the complete documentation index.

Read CONTRIBUTING.md before submitting a PR for code style, commit conventions, and the PR checklist.

Contributions generated entirely by LLMs without review or understanding are prohibited under Drips Wave terms.

CarbonChain is designed to work seamlessly across all major platforms:

• ✅ Linux (Ubuntu, Debian, Fedora, etc.)
• ✅ macOS (Intel and Apple Silicon)
• ✅ Windows (10/11 with PowerShell + WSL2)

• Linux / macOS: see main setup instructions above
• Windows: see WINDOWS_SETUP.md for detailed WSL2 configuration

See SECURITY.md for the vulnerability reporting and responsible disclosure process.

• No private keys in the API — all user-facing transactions signed client-side via Freighter
• Stable error codes (100–126) for API compatibility across contract upgrades
• Replay protection at multiple contract levels with nonce-based verification
• Immutable audit logs — no delete functions on retirement or session records
• Authorization checks on all state-mutating operations
• .claudeignore excludes ADMIN_SECRET_KEY and all secrets from Claude Code context
• cargo audit runs in CI on every push/PR — high-severity CVEs in Rust dependencies fail the build

All existing contract methods remain unchanged. Session features are opt-in, allowing gradual adoption without breaking existing integrations.

• Project architecture & documentation
• Soroban credit registry contract (v1)
• Soroban retirement contract
• Soroban marketplace contract
• Soroban MRV oracle contract
• NestJS API scaffold with Stellar SDK integration
• Angular marketplace frontend
• Verifier multi-sig flow with reputation scoring
• IPFS project document upload
• MRV oracle integration
• Credit transfer (OTC), splitting, merging, and batch retirement
• Session traceability & immutable audit trail
• Nonce-based replay protection on all contract operations
• SEP-10 Freighter wallet authentication (JWT)
• Docker Compose full-stack setup
• CI/CD pipeline (GitHub Actions) with cargo audit
• Load testing scripts

• Retirement certificate PDF generation (endpoint exists, CertificateService needs wiring)
• Retirement certificate viewer UI (/certificates/:id)
• Mobile-responsive frontend layout
• Mainnet deployment with production hardening

• Limit order book — price/quantity matching beyond single-offer DEX listings
• Credit bundling — package multiple credits into a basket offer
• Automated market maker (AMM) pool for continuous liquidity
• Price history charts and market analytics dashboard
• Watchlist & price alerts for specific project credits
• Secondary market fee distribution to original project issuers

• Credit merging UI — frontend flow for the existing merge_credits contract function
• Credit expiry enforcement — automated cron for expire_credit past vintage cutoff
• Credit dispute resolution UI — verifier/admin panel for dispute workflow
• Fractional credit splitting wizard — step-by-step UI for split_credit
• Credit portfolio analytics — CO₂e exposure, vintage spread, methodology breakdown

• Verifier onboarding flow — self-service registration with document upload to IPFS
• Verifier reputation leaderboard — public ranking by approval count vs. dispute ratio
• MRV data dashboard — real-time satellite/IoT feed visualisation per project
• Anomaly alert notifications — push/email when MRV oracle flags a project
• Multi-oracle consensus — require N-of-M oracles to agree before flagging anomaly
• Automated re-verification triggers — disputed credits auto-queue for re-review

• Corporate buyer dashboard — aggregate retirement receipts grouped by scope (1/2/3)
• Exportable compliance reports — PDF/CSV for annual ESG disclosures
• API webhooks for retirement events — push notifications to buyer systems
• CORSIA / Article 6 labelling — compliance framework tags on credits
• Double-counting prevention registry — cross-check against national registries via API

• Freighter deep-link flows — one-click retirement from external dApps
• Public embeddable retirement widget — iframe badge for corporate sustainability pages
• REST API public developer portal — rate-limited open API with API key management
• Stellar federation address support — human-readable identifiers (e.g. company*carbonchain.io)
• Cross-chain bridge (EVM) — mirror retirement proofs on Ethereum/Polygon for DeFi integrations

• PostgreSQL read replica — geographic redundancy for high-read workloads
• Multi-region deployment — geographic redundancy for API and IPFS pinning
• On-chain governance — token-weighted voting on methodology standards and fee parameters
• Contract upgrade governance — time-locked multi-sig for WASM upgrades
• Public audit dashboard — real-time contract state explorer for transparency

License: MIT Stellar — see the LICENSE file for details.

For questions or issues:

• Check the docs/ documentation files
• Review the API specification at /api/docs
• Examine the test cases in contracts/*/src/lib.rs
• Open a GitHub issue at [email protected]:legend-esc/carbonchain.git

Built on Stellar