Celo - Mobile-First Blockchain Platform Documentation

// Stable token addresses on Celo Mainnet
const STABLE_TOKENS = {
  cUSD: '0x765DE816845861e75A25fCA122bb6898B8B1282a',
  cEUR: '0xD8763CBa276a3738E6DE85b4b3bF5FDed6D6cA73',
  cREAL: '0xe8537a3d056DA446677B9E9d6c5dB704EaAb4787'
};

// Transfer cUSD
async function transferCUSD(to, amount) {
  const cUSD = new ethers.Contract(
    STABLE_TOKENS.cUSD,
    ['function transfer(address to, uint256 amount) returns (bool)'],
    signer
  );

  const tx = await cUSD.transfer(to, ethers.parseUnits(amount, 18));
  await tx.wait();
  return tx.hash;
}

// Verify phone number ownership (using Celo SDK)
import { OdisUtils } from '@celo/identity';

async function verifyPhoneNumber(phoneNumber, address) {
  // Get attestation service
  const attestations = await kit.contracts.getAttestations();

  // Request attestations
  const tx = await attestations.request(
    phoneNumber,
    3, // Number of attestations
    address
  );

  await tx.waitReceipt();

  // Complete verification process
  const attestationCode = await getAttestationCode(); // SMS verification
  await attestations.complete(phoneNumber, address, attestationCode);
}

// Configure transaction to pay fees in cUSD
async function sendWithStableFees(to, value) {
  const tx = {
    to,
    value: ethers.parseEther(value),
    feeCurrency: STABLE_TOKENS.cUSD, // Pay fees in cUSD
    gasLimit: 21000,
    gasPrice: await provider.getGasPrice()
  };

  const signedTx = await signer.signTransaction(tx);
  const receipt = await provider.sendTransaction(signedTx);
  return receipt;
}

class CeloWallet {
  constructor(provider, address) {
    this.provider = provider;
    this.address = address;
  }

  async getBalances() {
    const balances = {};

    // Get CELO balance
    balances.CELO = await this.provider.getBalance(this.address);

    // Get stable token balances
    for (const [symbol, address] of Object.entries(STABLE_TOKENS)) {
      const contract = new ethers.Contract(
        address,
        ['function balanceOf(address) view returns (uint256)'],
        this.provider
      );
      balances[symbol] = await contract.balanceOf(this.address);
    }

    return balances;
  }

  async getUSDValue() {
    const balances = await this.getBalances();
    let totalUSD = 0;

    // cUSD is pegged 1:1
    totalUSD += Number(ethers.formatUnits(balances.cUSD, 18));

    // Get CELO price from oracle
    const celoPrice = await this.getCELOPrice();
    totalUSD += Number(ethers.formatUnits(balances.CELO, 18)) * celoPrice;

    return totalUSD;
  }
}

// Ultralight client configuration
class MobileCeloClient {
  constructor(rpcUrl) {
    this.provider = new JsonRpcProvider(rpcUrl, {
      // Optimize for mobile
      timeout: 30000,
      throttleLimit: 1,
      throttleSlotInterval: 1000
    });

    // Cache frequently accessed data
    this.cache = new Map();
  }

  async getBlockHeader(blockNumber) {
    const key = `block_${blockNumber}`;

    if (this.cache.has(key)) {
      return this.cache.get(key);
    }

    // Fetch only essential fields for mobile
    const block = await this.provider.send('eth_getBlockByNumber', [
      ethers.toQuantity(blockNumber),
      false // Don't include transactions
    ]);

    const header = {
      number: block.number,
      hash: block.hash,
      timestamp: block.timestamp,
      gasUsed: block.gasUsed
    };

    this.cache.set(key, header);
    return header;
  }
}

// Stake CELO with validators
async function stakeCELO(validatorAddress, amount) {
  const election = await kit.contracts.getElection();
  const lockedGold = await kit.contracts.getLockedGold();

  // Lock CELO first
  await lockedGold.lock().sendAndWaitForReceipt({
    value: amount
  });

  // Vote for validator
  await election.vote(validatorAddress, amount)
    .sendAndWaitForReceipt();

  console.log(`Staked ${amount} CELO with validator ${validatorAddress}`);
}

// Get validator rewards
async function getRewards(address) {
  const election = await kit.contracts.getElection();
  const rewards = await election.getVoterRewards(address);
  return rewards;
}

import { Multicall } from '@celo/contractkit';

async function batchTokenBalances(addresses) {
  const multicall = new Multicall(kit);

  const calls = addresses.flatMap(addr =>
    Object.entries(STABLE_TOKENS).map(([symbol, token]) => ({
      target: token,
      callData: encodeBalanceOf(addr),
      symbol,
      address: addr
    }))
  );

  const results = await multicall.aggregate(calls);
  return parseResults(results);
}

// Query historical stable token prices
async function getHistoricalPrice(blockNumber) {
  const oracle = new ethers.Contract(
    ORACLE_ADDRESS,
    ['function getExchangeRate(address) view returns (uint256, uint256)'],
    provider
  );

  // Use archive node to query past state
  const [numerator, denominator] = await oracle.getExchangeRate(
    STABLE_TOKENS.cUSD,
    { blockTag: blockNumber }
  );

  return numerator / denominator;
}

async function syncTransfers(fromBlock, toBlock) {
  const filter = {
    address: STABLE_TOKENS.cUSD,
    topics: [ethers.id('Transfer(address,address,uint256)')],
    fromBlock,
    toBlock
  };

  // Process in chunks to avoid timeouts
  const chunkSize = 1000;
  const events = [];

  for (let i = fromBlock; i <= toBlock; i += chunkSize) {
    const chunk = await provider.getLogs({
      ...filter,
      fromBlock: i,
      toBlock: Math.min(i + chunkSize - 1, toBlock)
    });
    events.push(...chunk);
  }

  return events;
}

# Install Celo CLI
npm install -g @celo/celocli

# Create new project
npx create-react-app my-celo-dapp
cd my-celo-dapp

# Install Celo dependencies
npm install @celo/contractkit ethers

// src/celo.js
import { newKit } from '@celo/contractkit';

export const kit = newKit(
  'https://api-celo-mainnet-archive.n.dwellir.com/YOUR_API_KEY'
);

// src/App.js
import { useState, useEffect } from 'react';
import { kit } from './celo';

function App() {
  const [account, setAccount] = useState('');
  const [balance, setBalance] = useState('0');

  useEffect(() => {
    connectWallet();
  }, []);

  async function connectWallet() {
    // Connect to Celo wallet
    const accounts = await kit.web3.eth.getAccounts();
    setAccount(accounts[0]);

    // Get balance
    const bal = await kit.getTotalBalance(accounts[0]);
    setBalance(bal.CELO.toString());
  }

  return (
    <div>
      <h1>My Celo dApp</h1>
      <p>Account: {account}</p>
      <p>Balance: {balance} CELO</p>
    </div>
  );
}

// Mobile-optimized provider configuration
const mobileConfig = {
  // Reduce timeout for mobile networks
  timeout: 20000,

  // Enable compression
  headers: {
    'Accept-Encoding': 'gzip, deflate'
  },

  // Retry logic for unstable connections
  retry: {
    retries: 3,
    minTimeout: 1000,
    maxTimeout: 5000
  }
};

// Detect mobile and adjust accordingly
const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);

const provider = new JsonRpcProvider(
  'https://api-celo-mainnet-archive.n.dwellir.com/YOUR_API_KEY',
  isMobile ? mobileConfig : {}
);

// Connect to Alfajores testnet
const testnetProvider = new JsonRpcProvider(
  'https://api-celo-alfajores.n.dwellir.com/YOUR_API_KEY'
);

// Alfajores faucet
// Visit: https://faucet.celo.org

// Testnet stable tokens
const ALFAJORES_TOKENS = {
  cUSD: '0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1',
  cEUR: '0x10c892A6EC43a53E45D0B916B4b7D383B1b78C0F'
};

// Before (Ethereum)
const provider = new JsonRpcProvider('https://eth-rpc.example.com');
const tx = {
  to: recipient,
  value: amount,
  gasPrice: await provider.getGasPrice()
};

// After (Celo)
const provider = new JsonRpcProvider(
  'https://api-celo-mainnet-archive.n.dwellir.com/YOUR_API_KEY'
);
const tx = {
  to: recipient,
  value: amount,
  gasPrice: await provider.getGasPrice(),
  feeCurrency: STABLE_TOKENS.cUSD // Optional: pay fees in cUSD
};

// EVM compatible - contracts work without changes
// Same Web3 libraries and tools
// Note: Different chain ID (42220)
// Note: Additional features: stable tokens, phone verification
// New capability: multi-currency gas payments