Entangle Smart Contracts

Cairo smart contracts for the Entangle meeting auction platform on Starknet.

Features

• 🎯 Meeting auction contract
• 💰 Token factory for creator tokens
• 🏊 Pool manager for liquidity
• 🔒 Secure and audited patterns
• ⚡ Gas-optimized implementations

Tech Stack

• Language: Cairo 2.x
• Build Tool: Scarb
• Network: Starknet (Sepolia Testnet)
• Testing: Starknet Foundry

Prerequisites

• Scarb (Cairo package manager)
• Starknet Foundry (for testing)
• Node.js (for deployment scripts)

Installation

Install Scarb

# macOS/Linux
curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | sh

# Or use asdf
asdf plugin add scarb
asdf install scarb latest
asdf global scarb latest

Install Starknet Foundry

curl -L https://raw.githubusercontent.com/foundry-rs/starknet-foundry/master/scripts/install.sh | sh

Install Dependencies

# Install Cairo dependencies
scarb build

Project Structure

contract/
├── src/
│   ├── auction.cairo          # Main auction contract
│   ├── token_factory.cairo    # Creator token factory
│   ├── pool_manager.cairo     # Liquidity pool manager
│   └── lib.cairo             # Library exports
├── tests/
│   ├── test_auction.cairo    # Auction tests
│   ├── test_factory.cairo    # Factory tests
│   └── test_pool.cairo       # Pool tests
├── scripts/
│   ├── deploy.sh             # Deployment script
│   ├── build.sh              # Build script
│   └── test.sh               # Test script
├── Scarb.toml                # Scarb configuration
└── README.md

Contracts

Meeting Auction Contract

Main contract for creating and managing meeting auctions.

Features:

• Create time-based auctions
• Place bids with STRK tokens
• Automatic winner selection
• Meeting NFT minting for winners

Key Functions:

fn create_auction(
    title: felt252,
    description: felt252,
    start_time: u64,
    end_time: u64,
    min_bid: u256
) -> u256

fn place_bid(auction_id: u256, amount: u256)

fn end_auction(auction_id: u256)

fn claim_meeting_nft(auction_id: u256)

Token Factory Contract

Factory for creating and managing creator tokens.

Features:

• Deploy ERC20 tokens for creators
• Bonding curve pricing
• Automatic liquidity provision
• Creator royalties

Key Functions:

fn create_token(
    name: felt252,
    symbol: felt252,
    initial_supply: u256
) -> ContractAddress

fn buy_tokens(token_address: ContractAddress, amount: u256)

fn sell_tokens(token_address: ContractAddress, amount: u256)

Pool Manager Contract

Manages liquidity pools for creator tokens.

Features:

• Create liquidity pools
• Add/remove liquidity
• Swap tokens
• Fee distribution

Key Functions:

fn create_pool(
    token_a: ContractAddress,
    token_b: ContractAddress
) -> ContractAddress

fn add_liquidity(
    pool: ContractAddress,
    amount_a: u256,
    amount_b: u256
)

fn swap(
    pool: ContractAddress,
    token_in: ContractAddress,
    amount_in: u256
) -> u256

Development

Build Contracts

# Build all contracts
scarb build

# Or use the build script
./scripts/build.sh

Run Tests

# Run all tests
scarb test

# Run specific test
scarb test test_auction

# Or use the test script
./scripts/test.sh

Format Code

# Format Cairo code
scarb fmt

Deployment

Starknet Sepolia Testnet

# Set environment variables
export STARKNET_RPC_URL="https://starknet-sepolia-rpc.publicnode.com"
export STARKNET_ACCOUNT="your_account_address"
export STARKNET_PRIVATE_KEY="your_private_key"

# Deploy contracts
./scripts/deploy.sh

Manual Deployment

# Declare contract class
starkli declare target/dev/entangle_MeetingAuction.sierra.json \
  --account ~/.starkli-wallets/deployer/account.json \
  --keystore ~/.starkli-wallets/deployer/keystore.json

# Deploy contract instance
starkli deploy <CLASS_HASH> \
  <CONSTRUCTOR_ARGS> \
  --account ~/.starkli-wallets/deployer/account.json \
  --keystore ~/.starkli-wallets/deployer/keystore.json

Deployed Contracts (Sepolia)

Meeting Auction: 0x05e15d1c407510d2ab83c24c59c06ad473f2d58f069df764a0bdbc9126447331
Pool Manager:    0x049d121db1acfe975c9e374459eff9b34abeb64025ecf2fea05f7574ad9563e7
Token Factory:   0x01f31b4a185088bf5f248b7b8d5d6295906030eab4dc07da6ac27b4ba86c3c8f
tBTC Token:      0x03d3d97305e3d5546a3b80746856a348a14a453296acd7b945f76be8b01cca3b

Testing

Unit Tests

# Run unit tests
scarb test

Integration Tests

# Run integration tests
scarb test --integration

Coverage

# Generate coverage report
scarb test --coverage

Security

Audit Checklist

• Reentrancy protection
• Integer overflow/underflow checks
• Access control validation
• Input validation
• Event emission
• Gas optimization

Best Practices

• Use OpenZeppelin Cairo contracts where possible
• Follow Cairo naming conventions
• Add comprehensive tests
• Document all public functions
• Use events for state changes

Gas Optimization

• Minimize storage reads/writes
• Use felt252 instead of u256 where possible
• Batch operations when feasible
• Cache frequently accessed values
• Use view functions for read-only operations

Troubleshooting

Build Errors

# Clean build artifacts
scarb clean

# Rebuild
scarb build

Test Failures

# Run tests with verbose output
scarb test -v

# Run specific test
scarb test test_name -v

Deployment Issues

• Verify account has sufficient ETH for gas
• Check RPC URL is correct
• Ensure account is deployed on network
• Verify constructor arguments are correct

Resources

• Cairo Book
• Starknet Documentation
• Scarb Documentation
• Starknet Foundry
• OpenZeppelin Cairo

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run scarb fmt and scarb test
6. Submit a pull request

License

MIT

Support

For issues and questions, please open an issue on GitHub.