🚀 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)

Repository Connection: Link GitHub repository to Vercel dashboard

Environment Configuration:

LIGHTHOUSE_API_KEY=your_lighthouse_api_key_here

Automatic Deployment: Vercel detects Next.js configuration and builds
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

Creative Upload: Content submission and rendering pipeline
Auction Dynamics: Queue prioritization and bid processing
Lifecycle Management: Automatic expiration and rotation validation
Data Durability: Persistence across deployment cycles
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:

Fork Repository: Create your own branch of the codebase
Feature Branch: git checkout -b feature/innovative-enhancement
Implementation: Adhere to established patterns and conventions
Quality Assurance: Validate all functionality with comprehensive tests
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

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
ad402-sdk		ad402-sdk
agents		agents
app		app
soroban-hello-world		soroban-hello-world
README.md		README.md

NishantSinghhhhh/Doetnv

Folders and files

Latest commit

History

Repository files navigation