🚀 SwiftAd - Web3 Advertising Infrastructure

A next-generation advertising platform leveraging blockchain technology, distributed storage, and dynamic bidding mechanisms for trustless, decentralized ad management.

🎯 Platform Overview

SwiftAd represents a fully decentralized advertising infrastructure that transforms the relationship between content creators and brands. Engineered for the Web3 landscape, it delivers:

• 🔗 On-Chain Payments: Trustless USDC settlements using EIP-3009 protocol
• 🌐 Distributed Storage: Permanent, censorship-resistant hosting via IPFS
• ⚡ Dynamic Auction System: Market-driven pricing for premium ad inventory
• 📱 Contemporary Interface: Sleek, adaptive design with native Web3 support
• 🛠️ Integration SDK: Plug-and-play solution for any digital property

🏆 Project Highlights

Built as a comprehensive Web3 advertising infrastructure showcasing:

• End-to-end implementation using Next.js and TypeScript
• Smart contract integration with USDC payment rails and wallet connectivity
• Distributed storage architecture powered by IPFS and Lighthouse
• Live production environment hosted on Vercel
• Publisher-ready SDK enabling seamless integration

🏗️ System Architecture

📁 Repository Layout

mono-repo/
├── 🎨 app/                          # Core Next.js Platform
│   ├── app/                         # App Router Structure
│   │   ├── api/                     # Backend API Layer
│   │   │   ├── ads/[slotId]/        # Ad serving & retrieval
│   │   │   ├── upload-ad/           # Content upload handler
│   │   │   ├── queue-info/[slotId]/ # Auction queue control
│   │   │   ├── analytics/           # Performance monitoring
│   │   │   └── test-expiration/     # Development utilities
│   │   ├── checkout/                # Transaction & bidding UI
│   │   ├── upload/                  # Content submission portal
│   │   ├── dashboard/               # Creator metrics panel
│   │   └── example-ads/             # Live demonstration slots
│   ├── components/                  # UI Building Blocks
│   │   ├── SwiftAdSlot.tsx          # Primary slot renderer
│   │   ├── AdSlot.tsx               # Secondary slot variant
│   │   ├── WalletConnectModal.tsx   # Web3 wallet bridge
│   │   └── ui/                      # Component primitives
│   ├── lib/                         # Business Logic
│   │   ├── lighthouse.ts            # Distributed storage layer
│   │   ├── adService.ts             # Ad lifecycle management
│   │   ├── usdc.ts                  # Payment processing
│   │   └── walletConnect.ts         # Wallet orchestration
│   └── types/                       # Type definitions
├── 📦 ad402-sdk/                    # Publisher Integration Kit
│   ├── src/                         # SDK Implementation
│   │   ├── components/              # Exportable components
│   │   │   ├── SwiftAdProvider.tsx  # Configuration provider
│   │   │   └── SwiftAdSlot.tsx      # Slot implementation
│   │   ├── types/                   # Interface definitions
│   │   └── utils/                   # Helper functions
│   ├── examples/                    # Usage demonstrations
│   │   ├── basic-usage.tsx          # Minimal setup
│   │   └── nextjs-example.tsx       # Framework integration
│   └── dist/                        # Compiled distribution
├── ⚡ mainnet-facilitator/          # Payment Processor
│   └── index.ts                     # Settlement orchestrator
└── 🔧 service/                      # Supporting Services
    ├── src/                         # Implementation code
    └── routes/                      # Endpoint definitions

🚀 Core Capabilities

💰 Settlement Infrastructure

• USDC Integration: Standards-compliant token transfers via EIP-3009
• X402 Framework: Optimized for micropayment workflows
• Universal Wallet Support: Compatible with MetaMask, WalletConnect, and alternatives
• Polygon Settlement Layer: Minimal fees, instant finality

🎯 Inventory Management

• Standard Formats: Banner (728x90), Square (300x250), Mobile (320x60), Sidebar (160x600)
• Vertical Targeting: Technology, General, and Demo classifications
• Live Availability: Real-time occupancy and expiration tracking
• Lifecycle Automation: Time-bound ad rotation management

⚡ Auction Mechanism

• Open Inventory: Instant acquisition at floor price
• Occupied Positions: Competitive bidding for upcoming slots
• Priority Queue: Top bids secure next-available placement
• Seamless Transitions: Automatic activation upon slot expiration

🌐 Storage Infrastructure

• IPFS Foundation: All creative assets hosted on decentralized network
• Permanent Availability: Content persists beyond server lifecycles
• Geographic Distribution: Worldwide delivery via IPFS nodes
• Performance Optimization: 30-second caching layer

📦 Publisher SDK

The SwiftAd SDK enables effortless integration of decentralized advertising across any web property:

🎯 Rapid Setup

// 1. Add SDK dependency
npm install ad402-sdk

// 2. Configure your application
import { SwiftAdProvider } from 'ad402-sdk';

export default function RootLayout({ children }) {
  return (
    <SwiftAdProvider
      config={{
        websiteId: 'your-website-id',
        walletAddress: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
        apiBaseUrl: 'https://ad402.io',
      }}
    >
      {children}
    </SwiftAdProvider>
  );
}

// 3. Deploy ad inventory across your site
import { SwiftAdSlot } from 'ad402-sdk';

export default function HomePage() {
  return (
    <div>
      <h1>Welcome to My Website</h1>
      
      {/* Top banner placement */}
      <SwiftAdSlot
        slotId="header-banner"
        size="banner"
        price="0.25"
        category="technology"
      />
      
      <main>
        <p>Your content here...</p>
      </main>
      
      {/* Vertical sidebar unit */}
      <SwiftAdSlot
        slotId="sidebar-ad"
        size="sidebar"
        price="0.15"
        category="general"
      />
    </div>
  );
}

🎨 Extended Configuration

const advancedConfig = {
  websiteId: 'your-website-id',
  walletAddress: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
  apiBaseUrl: 'https://ad402.io',
  theme: {
    primaryColor: '#1a1a1a',
    backgroundColor: '#f8f9fa',
    textColor: '#333333',
    borderColor: '#dee2e6',
    fontFamily: 'Inter, sans-serif',
    borderRadius: 8
  },
  payment: {
    networks: ['polygon', 'ethereum'],
    defaultNetwork: 'polygon',
    recipientAddress: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6'
  },
  defaultSlotConfig: {
    durations: ['1h', '6h', '24h', '7d'],
    clickable: true
  }
};

🔧 Supported Slot Dimensions

Format	Dimensions	Optimal Placement
banner	728x90px	Page headers, footers
square	300x250px	Content sidebars, inline units
mobile	320x60px	Mobile-optimized layouts
sidebar	160x600px	Long-form vertical spaces

🛠️ Technical Foundation

🔗 Blockchain Layer

• EIP-3009 Compliance: Secure, auditable USDC movements
• X402 Standard: Purpose-built for ad micropayments
• Polygon Infrastructure: Sub-second confirmations, negligible gas
• Web3 Compatibility: Universal wallet integration layer

🌐 Storage Design

• Lighthouse/IPFS Core: Censorship-resistant content delivery
• HTTP Transport: Zero native dependencies, pure web standards
• Deployment Resilience: Data survives function cold starts
• Edge Distribution: Content served from nearest IPFS gateway

⚡ API Interface

• GET /api/ads/[slotId] - Fetch current ad for inventory slot
• POST /api/upload-ad - Submit new advertising creative
• GET /api/queue-info/[slotId] - Retrieve auction queue state
• POST /api/analytics/ad-view - Log impression events
• POST /api/analytics/ad-click - Record engagement metrics
• GET /api/health - Platform status verification

🚀 Launch Guide

📋 Requirements

• Node.js 18 or higher
• Lighthouse.storage credentials
• Web3-enabled wallet (MetaMask recommended)
• USDC balance on Polygon network

🔧 Development Environment

# Clone source repository
git clone https://github.com/ad402/mono-repo.git
cd mono-repo

# Install project dependencies
cd app
npm install

# Configure environment
cp .env.example .env.local
# Insert your LIGHTHOUSE_API_KEY

# Launch development server
npm run dev

📦 SDK Development Workflow

# Access SDK workspace
cd ad402-sdk

# Install dependencies
npm install

# Compile SDK package
npm run build

# Enable hot reload for development
npm run dev

🌐 Production Deployment

Vercel Hosting (Primary Method)

1. Repository Connection: Link GitHub repository to Vercel dashboard
2. Environment Configuration:

   LIGHTHOUSE_API_KEY=your_lighthouse_api_key_here

3. Automatic Deployment: Vercel detects Next.js configuration and builds
4. Validation: Confirm ad lifecycle and data persistence functionality

Required Environment Variables

# Production essentials
LIGHTHOUSE_API_KEY=your_lighthouse_api_key_here

# Optional - for data migration
LIGHTHOUSE_STORAGE_HASH=your_existing_ipfs_hash

🎨 Design System

🎯 Visual Philosophy

• Contemporary Minimalism: Refined, professional aesthetic
• Monospace Typeface: JetBrains Mono for technical precision
• Geometric Styling: Angular edges for crisp, modern appearance
• Achromatic Scheme: High-contrast black, white, and gray foundation
• Adaptive Layout: Fluid responsiveness across viewport sizes

🧩 Component Library

• SwiftAdSlot: Primary inventory unit with integrated bidding
• Checkout Interface: Streamlined payment and auction workflow
• Upload Portal: Intuitive creative submission with progress indicators
• Analytics Dashboard: Publisher performance and revenue insights

🔒 Security Architecture

• On-Chain Settlements: Immutable payment audit trail via blockchain
• Distributed Hosting: Decentralized storage eliminates central vulnerabilities
• Cryptographic Authentication: Web3 wallet-based identity verification
• Request Throttling: API rate limiting prevents resource exhaustion
• Schema Validation: Comprehensive input sanitization and type checking
• Origin Controls: Properly configured CORS policies

📊 Observability

• Engagement Metrics: Click-through rates and impression tracking
• Revenue Intelligence: Payment volume and bidding analytics
• Auction Performance: Queue depth and bid distribution monitoring
• Storage Telemetry: IPFS node health and retrieval latency
• Live Status: Real-time inventory availability and queue updates

🧪 Quality Assurance

🎯 Testing Endpoints

• /api/test-expiration - Generate test ads with configurable TTL
• /example-ads - Interactive showcase of all slot formats
• /test-ads - Development sandbox environment

🔍 Validation Scenarios

1. Creative Upload: Content submission and rendering pipeline
2. Auction Dynamics: Queue prioritization and bid processing
3. Lifecycle Management: Automatic expiration and rotation validation
4. Data Durability: Persistence across deployment cycles
5. Transaction Flow: End-to-end USDC payment verification

🌟 Production Characteristics

⚡ Horizontal Scalability

• Serverless Foundation: Elastic scaling via Vercel infrastructure
• Distributed Delivery: Global IPFS content replication
• Intelligent Caching: 30-second TTL for optimal performance
• Efficient Queuing: Low-latency auction state management

🛡️ System Reliability

• Decentralized Architecture: No single point of failure
• Graceful Degradation: Comprehensive error recovery mechanisms
• Stateful Persistence: Data survives infrastructure changes
• Event-Driven Updates: Reactive inventory and queue synchronization

📈 Roadmap

• Cross-Chain Expansion: Ethereum mainnet, Arbitrum, Optimism support
• Enhanced Analytics: Granular performance attribution and funnel analysis
• Creative Optimization: Multivariate testing framework
• Native Applications: iOS and Android mobile clients
• Ecosystem Integration: Third-party marketplace and API connectors
• Intelligent Targeting: Machine learning-powered placement optimization
• NFT Experiences: Tokenized ad units and collectible campaigns

🤝 Contribution Guidelines

We encourage community participation! Here's your pathway to contributing:

1. Fork Repository: Create your own branch of the codebase
2. Feature Branch: git checkout -b feature/innovative-enhancement
3. Implementation: Adhere to established patterns and conventions
4. Quality Assurance: Validate all functionality with comprehensive tests
5. Pull Request: Submit with detailed description of modifications

🎯 Coding Standards

• TypeScript mandatory for all new implementations
• Maintain consistency with existing style patterns
• Include test coverage for new capabilities
• Keep documentation synchronized with code changes
• Verify mobile and responsive behavior

---

SwiftAd - Transforming digital advertising through decentralization and cryptographic trust. 🚀

Crafted with ❤️ for the Web3 ecosystem