🏛️ Biequity

Decentralized Tokenized Stock Trading Platform

Issue, trade, and redeem fully-backed tokenized equities with transparent onchain collateral

🚀 Live Demo · 📖 Documentation · 🐛 Report Bug · 💡 Request Feature

🌟 Overview

Biequity is a revolutionary DeFi protocol that bridges traditional stock markets with blockchain technology. Built on Base, it enables users to mint, trade, and redeem tokenized equities backed by transparent onchain collateral using stablecoins.

✨ Key Features

🔒 Fully Collateralized - Every stock token is backed 1:1 with USDC collateral
📈 Real-time Pricing - Integrated with Pyth Network oracles for live market data
🎯 Transparent Trading - All transactions and collateral visible onchain
🔄 Instant Settlement - Mint and redeem tokens instantly with smart contracts
🌐 Cross-platform - Web app + Farcaster Mini App integration
⚡ Built on Base - Fast, cheap transactions with Ethereum security

🎯 Use Cases

Retail Investors - Access fractional stock ownership with crypto
DeFi Traders - Trade tokenized equities in DeFi protocols
Portfolio Managers - Create diversified stock/crypto portfolios
International Users - Access US stocks without traditional barriers

🏗️ Architecture

📋 System Components

Component	Description	Technology
Smart Contracts	Core protocol logic, token minting, collateral management	Solidity ^0.8.13
Price Oracles	Real-time stock price feeds	Pyth Network
Frontend DApp	User interface for trading and portfolio management	Next.js 15, React 19
Farcaster Integration	Mini app for social trading	MiniKit SDK
Wallet Connection	Multi-wallet support and transaction signing	Reown AppKit, wagmi

🔧 Tech Stack

Blockchain & Smart Contracts

Solidity ^0.8.13 - Smart contract development
Foundry - Development framework and testing
OpenZeppelin - Security-audited contract libraries
Base Network - L2 scaling solution
Pyth Network - Decentralized price oracles

Frontend & User Interface

Next.js 15 - React framework with App Router
React 19 - Modern UI library with concurrent features
TypeScript 5.0 - Type-safe development
Tailwind CSS 4 - Utility-first styling
Radix UI - Accessible component primitives

Web3 Integration

wagmi 2.0 - React hooks for Ethereum
viem 2.0 - TypeScript interface for Ethereum
Reown AppKit - WalletConnect v2 integration
@tanstack/react-query 5 - Server state management

Developer Experience

Biome - Fast formatter and linter
Renovate - Dependency updates automation
pnpm - Efficient package manager

🚀 Quick Start

Prerequisites

Node.js >= 18.0.0
pnpm >= 8.0.0 (recommended) or npm/yarn
Git for version control

Installation

Clone the repository

git clone https://github.com/IbrahimIjai/biequity.git
cd biequity

Install dependencies
```
pnpm install
```

Environment setup

cp .env.example .env.local

Configure your environment variables:

NEXT_PUBLIC_URL=http://localhost:3000
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id

Run development server
```
pnpm dev
```
Open in browser Navigate to http://localhost:3000

🔧 Smart Contract Development

Navigate to contracts directory
```
cd contracts
```
Install Foundry dependencies
```
forge install
```
Compile contracts
```
forge build
```
Run tests
```
forge test
```

Deploy to Base Sepolia

forge create --rpc-url https://sepolia.base.org \
  --private-key $PRIVATE_KEY \
  src/BiequityCore.sol:BiequityCore

⚙️ Configuration

Environment Variables

Create a .env.local file in the root directory:

# Application URL
NEXT_PUBLIC_URL=https://yourdomain.com

# WalletConnect Configuration
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id

# Contract Addresses (Base Sepolia)
NEXT_PUBLIC_BIEQUITY_CORE_ADDRESS=0x...
NEXT_PUBLIC_USDC_ADDRESS=0x...

# Optional: Analytics and monitoring
NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-...

Smart Contract Configuration

Configure contract addresses in config/biequity-core-contract.ts:

export const biequityConfig = {
	address: process.env.NEXT_PUBLIC_BIEQUITY_CORE_ADDRESS as `0x${string}`,
	abi: biequityCoreAbi,
	chainId: 84532, // Base Sepolia
} as const;

Farcaster Mini App

Update Mini App settings in minikit.config.ts:

export const minikitConfig = {
	miniapp: {
		name: "biequity",
		subtitle: "Onchain Stock Issuance",
		description: "Issue and trade tokenized equities...",
		// ... other configuration
	},
};

📁 Project Structure

biequity/
├── 📱 app/                          # Next.js App Router
│   ├── (apps)/                     # App routes (authenticated)
│   │   └── trade/                  # Trading interface
│   ├── (marketing)/                # Marketing pages
│   │   ├── page.tsx               # Landing page
│   │   └── protocol/              # Protocol documentation
│   ├── api/                       # API routes
│   │   ├── auth/                  # Authentication
│   │   └── prices/                # Price data endpoints
│   ├── globals.css                # Global styles
│   ├── layout.tsx                 # Root layout with SEO
│   └── sitemap.ts                 # Dynamic sitemap
├── 🎨 components/                   # React components
│   ├── trade/                     # Trading-specific components
│   │   ├── trade-ui.tsx          # Main trading interface
│   │   ├── token-selector.tsx    # Token selection dialog
│   │   └── numerical-input.tsx   # Number input component
│   └── ui/                        # Shared UI components
├── ⚙️ config/                       # Configuration files
│   ├── biequity-core-contract.ts # Smart contract config
│   ├── web3.ts                   # Web3 provider setup
│   ├── seo.ts                    # SEO configuration
│   └── abi/                      # Contract ABIs
├── 📜 contracts/                    # Smart contracts (Foundry)
│   ├── src/                       # Solidity source files
│   │   ├── BiequityCore.sol      # Main protocol contract
│   │   ├── BiequityToken.sol     # ERC20 stock tokens
│   │   └── BiequityTokenFactory.sol # Token factory
│   ├── test/                      # Contract tests
│   ├── script/                    # Deployment scripts
│   └── foundry.toml              # Foundry configuration
├── 🪝 hooks/                        # Custom React hooks
│   ├── useBalances.ts            # Balance management
│   └── useStockPrices.ts         # Price data fetching
├── 📚 lib/                          # Utility libraries
│   ├── tokens-list.ts            # Supported tokens & Pyth feeds
│   ├── utils.ts                  # Helper functions
│   └── seo.ts                    # SEO utilities
├── 🔌 providers/                    # React context providers
│   ├── root-provider.tsx         # Root app providers
│   ├── minikit-provider.tsx      # Farcaster Mini App
│   ├── reown-wagmi.tsx          # Wallet connection
│   └── data-providers/           # Data management
├── 🗄️ store/                        # State management (Zustand)
│   ├── trade-store.ts            # Trading state
│   ├── prices-store.ts           # Price data state
│   └── balances-store.ts         # User balances
└── 🌐 public/                       # Static assets
    ├── icons/                     # App icons & favicons
    ├── images/                    # Screenshots & graphics
    └── tokens/                    # Token logos

🔑 Key Files

File	Purpose	Description
`contracts/src/BiequityCore.sol`	Protocol Logic	Main smart contract handling minting, trading, and redemption
`app/(apps)/trade/page.tsx`	Trading Interface	User-facing trading application
`hooks/useStockPrices.ts`	Price Data	Real-time price fetching from Pyth oracles
`lib/tokens-list.ts`	Token Configuration	Supported stocks and their Pyth feed IDs
`config/biequity-core-contract.ts`	Contract Integration	Frontend-contract connection setup

🧪 Testing

Smart Contract Tests

# Run all contract tests
cd contracts && forge test

# Run with gas reporting
forge test --gas-report

# Run specific test file
forge test --match-path test/BiequityCore.t.sol

# Run with verbosity for debugging
forge test -vvv

Frontend Testing

# Run component tests
pnpm test

# Run with coverage
pnpm test:coverage

# Run E2E tests
pnpm test:e2e

📈 Performance & Monitoring

Key Metrics

Gas Efficiency - Optimized contract calls averaging <50k gas per transaction
Price Accuracy - Sub-second price updates via Pyth Network oracles
UI Responsiveness - <100ms trade calculation updates
Bundle Size - <200KB initial JavaScript bundle

Monitoring Stack

Sentry - Error tracking and performance monitoring
Vercel Analytics - Real user metrics and Core Web Vitals
Dune Analytics - Onchain metrics and trading volume

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

TypeScript - Strict mode enabled
ESLint - Airbnb configuration
Prettier - Consistent code formatting
Husky - Pre-commit hooks for quality checks

🐛 Known Issues & Limitations

Price Latency - Oracle updates may have 1-2 second delays during high volatility
Gas Costs - Minting operations require ~80k gas on Base
Token Support - Currently limited to major US equities (AAPL, TSLA, MSFT)

Legal & Compliance

⚠️ Important Disclaimer: Biequity tokens are synthetic representations and not actual securities. This protocol is experimental software. Users should understand the risks involved in DeFi protocols.

Regulatory Status: Not available in restricted jurisdictions. Please consult local regulations before use.

📚 Resources

Documentation

Community

Security

🙏 Acknowledgments

Base Team - For the incredible L2 infrastructure
Pyth Network - For reliable price oracle services
OpenZeppelin - For battle-tested smart contract libraries
Farcaster Team - For Mini App framework and social integration

📊 Repository Stats

📖 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ by the Biequity Team

Website • Documentation • Discord • Twitter

⭐ Star us on GitHub if you find this project useful!

Name		Name	Last commit message	Last commit date
Latest commit History 155 Commits
.github		.github
app		app
cloudfare-worker		cloudfare-worker
components		components
config		config
contracts		contracts
hooks		hooks
lib		lib
providers		providers
public		public
store		store
.gitignore		.gitignore
.gitmodules		.gitmodules
FAVICON_GUIDE.md		FAVICON_GUIDE.md
README.md		README.md
SEO_GUIDE.md		SEO_GUIDE.md
biome.json		biome.json
components.json		components.json
foundry.lock		foundry.lock
minikit.config.ts		minikit.config.ts
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
renovate.json		renovate.json
tsconfig.json		tsconfig.json

IbrahimIjai/biequity

Folders and files

Latest commit

History

Repository files navigation

🏛️ Biequity

🌟 Overview

✨ Key Features

🎯 Use Cases

🏗️ Architecture

📋 System Components

🔧 Tech Stack

Blockchain & Smart Contracts

Frontend & User Interface

Web3 Integration

Developer Experience

🚀 Quick Start

Prerequisites

Installation

🔧 Smart Contract Development

⚙️ Configuration

Environment Variables

Smart Contract Configuration

Farcaster Mini App

📁 Project Structure

🔑 Key Files

🧪 Testing

Smart Contract Tests

Frontend Testing

📈 Performance & Monitoring

Key Metrics

Monitoring Stack

🤝 Contributing

Development Workflow

Code Standards

🐛 Known Issues & Limitations

Legal & Compliance

📚 Resources

Documentation

Community

Security

🙏 Acknowledgments

📊 Repository Stats

📖 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Packages