Decentralized content preservation with unified storage architecture - Built for permanence, optimized for performance.
# Install dependencies
npm install
# Start development server with Netlify Functions
npx netlify dev
# Start Vite only (limited functionality)
npm run dev
# Build for production
npm run build
# Type check
npm run type-checkEvermark Beta follows a feature-first architecture for maximum maintainability:
src/
├── core/ # Pure business logic, types, utilities
├── features/ # Self-contained feature modules
├── components/ # Reusable UI components
├── providers/ # React Context providers
├── lib/ # External service integrations
└── pages/ # Route components
- Unified Storage: Content preserved on ArDrive (Arweave) for permanence, IPFS for speed
- Feature Isolation: Each feature is independently testable and maintainable
- Pure Functions: All business logic as testable pure functions
- Single State Hook: One hook per feature for centralized state management
- Type Safety: Comprehensive TypeScript coverage with strict mode
- Clean Separation: UI components contain no business logic
- SDK-Powered: Core functionality provided by the evermark-sdk
- Season Management: Automated weekly seasons with smart contract coordination
- Evermarks: Create and manage on-chain content preservation (up to 25MB per file)
- Cast Backup: Full Farcaster cast preservation with searchable text and visual preview
- Staking: Lock $EMARK tokens to gain voting power
- Voting: Delegate voting power to quality content
- Leaderboard: Community-driven content rankings
- Tokens: Manage $EMARK balances and transactions
- Marketplace: Buy and sell Evermark NFTs with real-time listings
- Points System: Earn points for community participation and marketplace activity
- Season Management: Automated weekly progression with leaderboard finalization
- Advanced Analytics: Comprehensive data integrity and performance monitoring
- Unified Storage: ArDrive (Arweave) for permanent preservation, IPFS for fast access
- Content Limits: 25MB file size limit covering 95%+ of Farcaster content
- Skip-and-Link: Oversized media preserved via reference links
- Hybrid Caching: Supabase caching layer for optimal performance
- Farcaster Integration: Native Frame/Mini-app support with full cast text preservation
- Blockchain: Thirdweb SDK with Base network (Chain ID: 8453)
- Real-time Data: React Query with 30s stale time
- Responsive Design: Mobile-first with cyber theme
- SDK Integration: Powered by evermark-sdk for robust image/metadata handling
- Error Handling: Comprehensive error boundaries and validation
- Dynamic Sharing: Optimized social media integration with platform-specific meta tags
Evermark rewards community participation with a comprehensive points system designed to encourage quality content creation and marketplace activity.
| Action | Points | Description |
|---|---|---|
| Create Evermark | 10 points | Mint a new Evermark NFT with quality content |
| Vote on Content | 1 point | Delegate voting power to help curate quality |
| Stake $EMARK | 1 point/1M tokens | Lock tokens to gain voting power (minimum 1M $EMARK) |
| Buy NFT | 1 point | Purchase an Evermark from the marketplace |
| List NFT for Sale | 1 point | Create a marketplace listing for your Evermark |
The marketplace system is fully integrated with the points reward structure:
- Buying: Every successful NFT purchase earns 1 point automatically
- Selling: Creating a marketplace listing earns 1 point when the listing is created
- Real-time Updates: Points are awarded immediately upon transaction confirmation
- Cross-platform: Works in both browser and Farcaster miniapp environments
Content Creators: Focus on creating high-quality Evermarks (10 points each) and engaging with the community through voting (1 point each).
Collectors: Participate in the marketplace by buying quality Evermarks (1 point each) and listing your own collection (1 point per listing).
Stakeholders: Stake large amounts of $EMARK tokens for consistent point accumulation and increased voting power.
- View real-time rankings on the leaderboard
- Points are tracked permanently with full transaction history
- Top performers gain community recognition and influence
- Historical data preserved for long-term achievement tracking
The points system creates a sustainable economy that rewards both content creation and marketplace participation, driving organic growth and community engagement.
- Frontend: React 18 + TypeScript + Vite
- Styling: Tailwind CSS with custom cyber theme
- State Management: React Query + React Context
- Storage: ArDrive (Arweave) + IPFS (Pinata) + Supabase caching
- Blockchain: Thirdweb SDK + Wagmi + Viem (Base Network)
- Backend: Netlify Functions + Supabase
- Testing: Vitest + React Testing Library
User Upload → ArDrive (Permanent) → Blockchain (Metadata URI)
↓ ↓
IPFS (Fast) Supabase (Cache) ← Background Sync
Unified Storage Approach: Content stored on ArDrive (Arweave) for permanent preservation, IPFS for fast access, with Supabase providing optimized caching for the best user experience.
Each feature follows this pattern:
features/[feature-name]/
├── components/ # Feature-specific UI components
├── hooks/ # State management hooks
├── services/ # Pure business logic functions
├── types/ # TypeScript interfaces
└── index.ts # Public API exports
- Define Types: Create clear TypeScript interfaces
- Build Services: Pure functions for business logic
- Create Hook: Single state management hook
- Build Components: UI components that use the hook
- Export API: Clean public interface
- TypeScript strict mode with no
anytypes - ESLint + Prettier for consistent formatting
- Comprehensive error handling
- Unit tests for business logic
- Integration tests for hooks
Built for Netlify with:
- Automatic deployments from main branch
- Netlify Functions for backend API
- Environment variable management
- Edge caching for optimal performance
# Blockchain (Required)
VITE_THIRDWEB_CLIENT_ID=your_thirdweb_client_id
VITE_CHAIN_ID=8453 # Base mainnet
# Database (Required)
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_KEY=your_service_key # Backend only
# Storage Systems (Required)
# ArDrive (Arweave) - Primary permanent storage
VITE_ARDRIVE_API_KEY=your_ardrive_api_key
VITE_ARDRIVE_WALLET_KEY=your_ardrive_wallet_key
# IPFS - Fast access layer
VITE_PINATA_API_KEY=your_pinata_api_key
VITE_PINATA_SECRET_KEY=your_pinata_secret
VITE_PINATA_JWT=your_pinata_jwt
VITE_PINATA_GATEWAY=your_gateway_url
# Smart Contracts (Required)
VITE_EMARK_TOKEN_ADDRESS=0x...
VITE_CARD_CATALOG_ADDRESS=0x...
VITE_EVERMARK_NFT_ADDRESS=0x...
VITE_EVERMARK_VOTING_ADDRESS=0x...
VITE_EVERMARK_LEADERBOARD_ADDRESS=0x...
VITE_EVERMARK_REWARDS_ADDRESS=0x...
VITE_FEE_COLLECTOR_ADDRESS=0x...
VITE_MARKETPLACE_ADDRESS=0x...
# Farcaster Integration (Optional)
VITE_FARCASTER_DEVELOPER_FID=your_developer_fid
VITE_NEYNAR_API_KEY=your_neynar_key
VITE_FARCASTER_MINI_APP_ID=your_mini_app_id- Copy environment variables from
.env.local.example - Configure ArDrive for permanent storage
- Configure Pinata for IPFS uploads
- Set up Supabase database and storage
- Deploy smart contracts to Base network
- Run
npx netlify devfor full functionality
- CLAUDE.md - Complete development guide for Claude Code
- SEASON_MANAGEMENT_SYSTEM.md - Season orchestration and ArDrive integration
- Architecture Overview - Feature-first design principles
- Storage Architecture - Unified storage approach
- Environment Setup - Local development guide
The project uses evermark-sdk for core functionality:
- IPFS Uploads:
IPFSClient.uploadFile()for direct IPFS storage - Image Resolution: Smart fallback between IPFS gateways and Supabase cache
- Validation: URL, IPFS hash, and metadata validation utilities
- Storage Orchestration: Intelligent content delivery optimization
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Follow the feature-first architecture patterns
- Ensure type safety:
npm run type-check - Test locally:
npx netlify dev - Submit a pull request
- Feature Development: Each feature is self-contained in
src/features/[name]/ - Code Quality: ESLint + Prettier with strict TypeScript
- Testing: Vitest for business logic, React Testing Library for components
- Documentation: Update CLAUDE.md for architectural changes
MIT License - see LICENSE for details.
Evermark Beta v2.0 - Decentralized content preservation, built for permanence 🚀
Powered by ArDrive + IPFS, secured by blockchain, optimized for performance.