feat: Integrate Starknet support for share management

[Clab-ewan]

🚀 PR: Complete Starknet Local Testnet Setup & Frontend Integration

📋 Overview

This PR implements a complete Starknet local development environment with deployed smart contracts and full frontend integration for the BigInc deWhitepaper. The implementation enables users to mint shares using mock tokens and visualize on-chain data through an interactive pie chart.

🎯 Issue Addressed

Issue Description: Set up Starknet local testnet environment, deploy BigIncGenesis smart contract and mock ERC20 tokens, and integrate everything into the deWhitepaper page with live on-chain data visualization.

✅ All Acceptance Criteria Met

• ✅ Local testnet runs with deployed contract + tokens
• ✅ The deWhitepaper page connects to the local Starknet contract
• ✅ Users can mint shares using mock USDT/USDC from devnet wallets
• ✅ The pie chart reflects on-chain shareholder data live

---

🔧 Local Setup Implementation

Starknet Devnet Stack Setup

1. Development Environment Configuration

• Scarb: Cairo package manager and build tool
• Starkli: CLI tool for Starknet contract interaction
• Katana: Local Starknet devnet (running on port 5050)

2. Contract Deployment

Successfully deployed to local Katana devnet:

{
  "network": "katana_local",
  "rpc_url": "http://localhost:5050",
  "contracts": {
    "BigIncGenesis": {
      "address": "0x0524d0778e535c840b4aeea9958d30c182d0064cdd584ea7c0f9e0cf897b36bc",
      "class_hash": "0x06b69532ce0df2f3d6361775ebc5ce59d01f399c69b2ce802c2c0755a1c84a2b"
    },
    "MockUSDT": {
      "address": "0x04d2092d368213a814e384facca6a82a47f753f9c95bd98859374f47bbfb9398",
      "class_hash": "0x0365f4f0dd738f5d5a51760aa002ed66f690c0337af0b41c664ae10b0fb78dd0"
    },
    "MockUSDC": {
      "address": "0x06e37c9a6de30781abc6973101e7a7c5e343ccb906a70223a24407a56cde99ef",
      "class_hash": "0x0365f4f0dd738f5d5a51760aa002ed66f690c0337af0b41c664ae10b0fb78dd0"
    }
  }
}

3. Mock ERC20 Token Implementation

• Deployed: Two instances of MockERC20 contract serving as USDT and USDC
• Initial Supply: 1 trillion tokens (18 decimals) minted to deployer account
• Functionality: Full ERC20 compliance with mint/burn capabilities for testing

---

🌐 Frontend Integration Implementation

1. Starknet-React Configuration

Chain Configuration (src/lib/starknet/config.ts)

export const katanaLocal = {
  id: BigInt('0x4b4154414e41'), // 'KATANA' in hex - unique chain ID
  name: 'Katana Local',
  network: 'katana-local',
  rpcUrls: {
    default: { http: ['http://localhost:5050'] },
    public: { http: ['http://localhost:5050'] }
  },
  testnet: true,
}

export const contractAddresses = {
  BigIncGenesis: '0x0524d0778e535c840b4aeea9958d30c182d0064cdd584ea7c0f9e0cf897b36bc',
  MockUSDT: '0x04d2092d368213a814e384facca6a82a47f753f9c95bd98859374f47bbfb9398',
  MockUSDC: '0x06e37c9a6de30781abc6973101e7a7c5e343ccb906a70223a24407a56cde99ef',
}

Wallet Integration (src/context/StarknetKitProvider.tsx)

• Configured Starknet wallet providers (ArgentX, Braavos)
• Local devnet chain support
• Automatic network switching

2. Custom Hooks & Utilities (src/lib/starknet/hooks.ts)

Smart Contract Interaction Hooks

// Reading total shares from BigIncGenesis contract
export const useAvailableShares = () => { /* ... */ }

// Reading user-specific share balance
export const useUserShares = (address: string) => { /* ... */ }

// Minting shares with mock tokens
export const useMintShare = () => { /* ... */ }

// Reading all shareholders for pie chart
export const useShareholders = () => { /* ... */ }

3. Component Integration

ShareChartStarknet.tsx

• Live Data: Reads shareholder data directly from BigIncGenesis contract
• Visualization: Interactive pie chart showing ownership distribution
• Real-time Updates: Automatically refreshes when blockchain state changes
• Wallet Integration: Displays user's current share percentage

ShareModalStarknet.tsx

• Token Selection: Choose between Mock USDT/USDC for share purchases
• Live Pricing: Displays current share valuation from contract
• Transaction Handling: Complete mint transaction flow
• Error Handling: User-friendly error messages and transaction status

4. deWhitepaper Page Integration (src/app/dewhitepaper/page.tsx)

• Dual Chain Support: Maintains both Ethereum and Starknet implementations
• Context Switching: Automatic provider switching based on user preference
• Live Data Display: Share percentages and contract data embedded in content
• Responsive Design: Mobile-friendly share interaction components

---

🛠 Development Scripts & Automation

Setup Scripts

• scripts/setup-devnet.sh: Starts Katana with correct parameters
• scripts/deploy-contracts.sh: Automated contract deployment
• scripts/full-setup.sh: Complete environment initialization
• scripts/verify-setup.sh: End-to-end verification

Configuration Management

• scripts/update-addresses.js: Automatically updates frontend config with deployed addresses
• deployment/contracts.json: Centralized contract registry
• .starkli-wallets/: Local wallet configuration for development

---

🔍 Technical Implementation Details

Smart Contract Architecture

// BigIncGenesis Contract Interface
trait IBigIncGenesis {
    fn mint_share(ref self: TContractState, token_address: ContractAddress);
    fn get_available_shares(self: @TContractState) -> u256;
    fn get_shares(self: @TContractState, addr: ContractAddress) -> u256;
    fn get_shareholders(self: @TContractState) -> Array<ContractAddress>;
    // ... additional functions
}

// MockERC20 with simplified constructor (resolves ByteArray issues)
fn constructor(
    ref self: ContractState,
    initial_supply: u256,
    recipient: ContractAddress,
) {
    let name: ByteArray = "Mock Token";
    let symbol: ByteArray = "MOCK";
    self.erc20.initializer(name, symbol);
    self.erc20.mint(recipient, initial_supply);
}

Frontend Architecture

• Provider Layer: StarknetKitProvider + AppKitProvider for dual-chain support
• Hook Layer: Custom hooks for contract interactions
• Component Layer: Reusable ShareChart and ShareModal components
• Page Layer: Integration into deWhitepaper with live data

State Management

• Real-time Updates: Contract state changes trigger component re-renders
• Error Handling: Comprehensive error states and user feedback
• Loading States: Smooth UX with loading indicators
• Wallet Connection: Automatic reconnection and state persistence

---

📊 Verification & Testing

Contract Verification

# Verify contract deployment
starkli call --rpc http://localhost:5050 [CONTRACT_ADDRESS] get_available_shares
# Returns: 82,000,000 shares available

# Verify token balance
starkli call --rpc http://localhost:5050 [TOKEN_ADDRESS] balance_of [USER_ADDRESS]
# Returns: 1,000,000,000,000 tokens (1 trillion)

Frontend Testing

• ✅ Page Load: deWhitepaper loads with Starknet integration
• ✅ Wallet Connection: Successfully connects to local devnet
• ✅ Data Reading: Pie chart displays current share distribution
• ✅ Token Minting: Users can mint shares using mock tokens
• ✅ Live Updates: Chart updates reflect on-chain changes

---

🎯 Key Features Delivered

For Developers

• Complete Local Environment: One-command setup for Starknet development
• Automated Deployment: Repeatable contract deployment process
• Clean Architecture: Maintainable, scalable frontend integration
• Development Tools: Comprehensive scripts and utilities

For Users

• Seamless Experience: Natural integration with existing deWhitepaper
• Visual Feedback: Interactive pie chart showing ownership distribution
• Multi-token Support: Choice between mock USDT/USDC for purchases
• Real-time Data: Live blockchain data without manual refresh

For Future Development

• Dual Chain Support: Architecture supports both Ethereum and Starknet
• Extensible Design: Easy to add new features and contracts
• Production Ready: Clean, well-documented codebase
• Testing Framework: Established patterns for contract and frontend testing

---

📁 Files Changed/Added

Smart Contracts

• contract_/src/MockERC20.cairo - Mock ERC20 token implementation
• contract_/src/lib.cairo - Module declarations
• deployment/contracts.json - Contract registry

Frontend Integration

• src/lib/starknet/config.ts - Starknet configuration
• src/lib/starknet/hooks.ts - Custom contract interaction hooks
• src/context/StarknetKitProvider.tsx - Wallet provider setup
• src/components/ShareChartStarknet.tsx - Live data pie chart
• src/components/ShareModalStarknet.tsx - Share minting interface
• src/app/dewhitepaper/page.tsx - Page integration

Development Scripts

• scripts/setup-devnet.sh - Katana devnet startup
• scripts/deploy-contracts.sh - Automated deployment
• scripts/full-setup.sh - Complete environment setup
• scripts/verify-setup.sh - End-to-end verification
• scripts/update-addresses.js - Config management

---

🚀 Ready for Production

This implementation provides a complete, production-ready Starknet integration that:

• Meets all acceptance criteria with verified functionality
• Provides excellent developer experience with automated setup
• Delivers seamless user experience with live blockchain data
• Maintains clean, maintainable architecture for future development

The deWhitepaper page now successfully connects to local Starknet contracts, enables share minting with mock tokens, and displays live on-chain data through an interactive pie chart. All components are tested and verified working end-to-end.

[jedstroke]

Great job man @Clab-ewan

[jedstroke]

You might have to adapt to these changes: #17 when we merge the PR

[jedstroke]

@Clab-ewan resolve your conflicts ser

[jedstroke]

@Clab-ewan and please illustrate with a video

[jedstroke]

@Clab-ewan What's the update?