Overview

Welcome to the Opals Protocol technical documentation. This section provides everything developers need to integrate with, deploy, or extend the Opals ecosystem.

Why Integrate with Opals?

The Opals Protocol solves critical infrastructure problems that plague traditional crowdfunding and token launches:

Traditional Launch Problems:

Mercenary capital extracts value and leaves immediately
Liquidity gets rugpulled by project teams
Early supporters get dumped on by latecomers
Bots and snipers dominate fair launches
Complex multi-contract deployments require deep expertise

What Opals Enables:

Deploy complete project ecosystems in a single transaction
Guarantee permanent liquidity through cryptographic enforcement
Reward long-term commitment with mathematically proven multipliers
Launch resistant to bot manipulation through stepped pricing
Enable flexible staking with early exit penalties that reward diamond hands

Integration Options

1. Recipe-Based Deployment (Recommended)

Deploy complete project ecosystems using pre-built recipes:

// Deploy a complete project with markets, claims, and liquidity
OpalsRecipe.deployProject(
    "ProjectName",
    admin,
    marketConfig,
    launcherConfig
);

Benefits:

Single transaction deploys 10+ integrated contracts
Pre-wired relationships between components
Battle-tested configuration patterns
Gas-optimized through EIP-1167 minimal proxies

Use Cases:

Token launches with crowdfunding
Membership platforms with staking rewards
Projects requiring protocol fee distribution

2. Template-Based Custom Deployment

Build custom configurations using individual templates:

// Deploy specific components as needed
address project = factory.deployContract(TEMPLATE_PROJECT);
address market = factory.deployContract(TEMPLATE_STEPPED_MARKET);
address claim = factory.deployContract(TEMPLATE_PATRON_CLAIM);

Benefits:

Maximum flexibility in component selection
Custom wiring patterns for unique requirements
Pay only for components you need
Extensible through custom templates

Use Cases:

Novel economic models requiring custom logic
Integration with existing protocol infrastructure
Research and experimentation with new mechanisms

3. Direct Contract Integration

Integrate existing projects with specific Opals components:

// Add Opals distribution to existing token
distributor.updateClaimAddresses(patronClaim, vaultClaim);

// Enable Opals rewards for existing NFT
patronClaim.addCardSet(existingNFT, weight, maxSupply);

Benefits:

Add Opals features to existing projects
Gradual migration path from legacy systems
Minimal changes to existing architecture
Interoperability with established ecosystems

Use Cases:

Adding staking rewards to existing NFT collections
Enabling fair distribution for existing tokens
Retrofitting existing projects with PatronPower mechanics

Quick Start

Prerequisites

Development Environment:

Foundry - Solidity development toolkit
Node.js v18+ - JavaScript runtime
Git - Version control

Required Knowledge:

Solidity 0.8.20 programming
Uniswap V2 liquidity mechanics
ERC20 and ERC721 token standards
Factory and proxy patterns (EIP-1167)

Recommended Knowledge:

Aave V3 lending protocol
Time-locked staking mechanisms
Batch transaction patterns
Event-driven architectures

Installation

Clone the repository and install dependencies:

# Clone the repository
git clone https://github.com/OpalsProtocol/opals-contracts.git
cd opals-contracts

# Install Foundry dependencies
forge install

# Install Node dependencies (optional, for deployment scripts)
yarn install

Build and Test

# Compile all contracts
forge build

# Run the complete test suite (375 tests)
forge test

# Run specific test file
forge test --match-path test/templates/core/Project.t.sol

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

# Check test coverage
forge coverage

Deploy Your First Project

# Deploy to local testnet (requires Anvil running)
forge script script/Deploy.s.sol --rpc-url localhost --broadcast

# Deploy to Base Sepolia testnet
forge script script/Deploy.s.sol \
  --rpc-url https://sepolia.base.org \
  --broadcast \
  --verify \
  --private-key $PRIVATE_KEY

Core Concepts

Template Factory Pattern

All contracts deploy through OpalsFactory using EIP-1167 minimal proxies:

// Factory creates lightweight clones (~95% gas savings)
address clone = factory.deployContract(
    templateId,  // keccak256("PROJECT")
    initData     // abi.encode(name, admin)
);

Gas Savings:

Traditional deployment: ~4,000,000 gas
Minimal proxy deployment: ~200,000 gas
Savings: 3,800,000 gas (74.7% reduction)

PatronPower Economics

Opals uses PatronPower to determine reward distribution:

// PatronClaim: Permanent lock = 10x multiplier
patronPower = lpAmount * 10;

// VaultClaim: Time-based lock = 0-5x multiplier
patronPower = lpAmount * (lockDuration / 4years) * 5;

Economic Guarantees:

Early supporters always have highest multiplier (10x permanent)
Flexible stakers earn proportional to commitment (0-5x)
Early exit penalties redistribute to diamond hands
Mathematically impossible to game the system

Component Architecture

Projects consist of interconnected templates:

Project - Central coordination hub with bidirectional mappings
Markets - NFT sales (Stepped, Fixed, Members, Club)
Claims - Token distribution (Patron, Vault, Diamond)
Launchers - Liquidity provision (LiquidityLauncher)
Vaults - Yield generation (WorkLock with Aave V3)
Distributors - Protocol fee distribution

Each component communicates through the Project contract using standardized interfaces.

Next Steps

For Integration:

Review Integration Guide for deployment patterns
Study Contracts Reference for function signatures
Examine Architecture Overview for system design
Check Security for best practices

For Development:

Explore the test suite in /test for usage examples
Study existing recipes in /src/recipes for patterns
Review interfaces in /src/interfaces for contract APIs
Examine deployment scripts in /script for mainnet patterns

For Production Deployment:

Test thoroughly on Base Sepolia or Monad testnet
Review security considerations in Security
Prepare multi-sig for admin operations
Plan monitoring and alerting for critical events

Repository Structure

src/
├── factory/           # OpalsFactory (EIP-1167 deployment)
├── templates/         # Template contracts (core, markets, claims, launchers)
├── recipes/           # High-level orchestration (complete deployments)
├── tokens/            # ERC20/ERC721 implementations
├── uniswap/           # Uniswap V2 fork (Factory, Router, Pair)
├── vaults/            # Aave V3 integration
├── access/            # Access control (Vouch, Clubs, Members)
├── utils/             # Utilities (CloneFactory, ReentrancyGuard, Zap)
└── interfaces/        # Contract interfaces (46 files)

test/                  # Comprehensive test suite (375 tests)
script/                # Deployment scripts and helpers
docs/                  # Audit reports and documentation

Support and Resources

Documentation:

Architecture Overview - System design deep dive
Integration Guide - Deployment patterns
Contracts Reference - Function signatures
Security - Security model and audits

Development:

GitHub Repository
Test Suite: 375 tests with 99.7% coverage
CLAUDE.md: AI assistant guidance for the codebase

Community:

Discord: discord.gg/opals
Twitter: @OpalsProtocol
Website: opals.io

Production Status

Current Status: Production Ready (as of 2025-10-02)

Security: All HIGH severity issues resolved
Tests: 375/375 passing (100% coverage)
Audits: Comprehensive security review completed
Networks: Base, Optimism, Arbitrum, Monad ready

Deployed Contracts:

Base Sepolia: Available
Monad Testnet: Available
Mainnet: Coming soon

This protocol has been battle-tested with comprehensive security audits and extensive test coverage. The architecture is production-ready for mainnet deployment.

PreviousMaximizing Returns NextArchitecture Overview

Last updated 21 days ago