{"id":37475200,"url":"https://github.com/aboutcircles/oic_apps","last_synced_at":"2026-01-16T07:20:49.399Z","repository":{"id":317338730,"uuid":"1066448865","full_name":"aboutcircles/oic_apps","owner":"aboutcircles","description":"Repository to collect mini-apps for the Open Internet Club, fueled by $OPEN.","archived":false,"fork":false,"pushed_at":"2025-11-15T21:20:43.000Z","size":248,"stargazers_count":1,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-15T23:24:28.402Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aboutcircles.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-29T13:54:01.000Z","updated_at":"2025-11-15T21:20:47.000Z","dependencies_parsed_at":"2025-10-01T09:06:48.054Z","dependency_job_id":null,"html_url":"https://github.com/aboutcircles/oic_apps","commit_stats":null,"previous_names":["aboutcircles/oic_apps"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aboutcircles/oic_apps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aboutcircles%2Foic_apps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aboutcircles%2Foic_apps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aboutcircles%2Foic_apps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aboutcircles%2Foic_apps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aboutcircles","download_url":"https://codeload.github.com/aboutcircles/oic_apps/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aboutcircles%2Foic_apps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-16T07:20:44.307Z","updated_at":"2026-01-16T07:20:49.388Z","avatar_url":"https://github.com/aboutcircles.png","language":"JavaScript","funding_links":[],"categories":["Build a Mini App"],"sub_categories":[],"readme":"# OIC Framework\n\n\u003e A blockchain-powered web application platform for building interactive, decentralized apps with minimal configuration.\n\nThe **App Framework** enables developers easily build mini-apps that are fueled by the $OPEN.\n\n## 🌟 Features\n\n### Core Framework Capabilities\n- 🎯 **Metadata-driven app creation** - Define apps with simple configuration objects\n- 💰 **Token-based interactions** - Built-in payment handling for $OPEN tokens\n- 📱 **Real-time QR code generation** - Dynamic payment requests and transfers\n- ⚡ **Live blockchain monitoring** - Real-time event listening and updates\n- 🔄 **Socket.io integration** - Instant updates across connected clients\n\n### Blockchain Integration\n- 🔗 **Circles protocol support** - Convert Circles tokens to $OPEN\n- 💎 **Ethers.js integration** - Full blockchain interaction capabilities\n- 📡 **Circles RPC monitoring** - Track blockchain events in real-time\n- 🔐 **Recipient address validation** - Secure payment processing\n\n### Data Persistence\n- 🗄️ **On-chain data source** - Query application events directly from Circles RPC\n- 🔄 **Real-time sync** - Automatic updates across all clients\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Node.js 18+ and npm\n- Git\n\n### Installation\n\n1. **Clone and install dependencies**\n   ```bash\n   cd oic_apps\n   npm install\n   ```\n\n2. **Configure environment variables**\n   ```bash\n   # Copy the example environment file\n   cp .env.example .env.local\n\n   # Edit .env.local with your configuration\n   nano .env.local\n   ```\n\n3. **Run the development server**\n   ```bash\n   npm run dev\n   ```\n\n4. **Open your browser**\n   - Navigate to http://localhost:3000\n   - Explore the available apps and framework features\n\n## 📱 Built-in Applications\n\nThe OIC Framework comes with several example applications demonstrating different use cases:\n\n### 1. **Mint $OPEN** (`/apps/mint-open`)\nConvert your Circles tokens to $OPEN tokens using maximum flow path calculations.\n\n**Features:**\n- Real-time wallet connection\n- Maximum flow calculation via Circles RPC\n- Dynamic amount selection\n- QR code generation for payments\n- Transaction verification and confirmation\n\n\n## 🏗️ Framework Architecture\n\n### Technology Stack\n- **Frontend**: Next.js 14 with React 18\n- **Real-time**: Socket.io for live updates\n- **Blockchain**: Ethers.js for Web3 interactions\n- **Data sources**: Circles RPC for events, Supabase for app data\n- **Styling**: CSS-in-JS with responsive design\n- **Deployment**: Docker-ready with multiple deployment options\n\n### Core Components\n\n#### OIC App Factory (`lib/oic-framework.js`)\nThe heart of the framework that creates apps from metadata:\n\n```javascript\nconst metadata = {\n  appId: \"my-app\",\n  title: \"My App Title\",\n  description: \"What this app does\",\n  recipient: \"0x...\", // Payment recipient address\n  initialState: { /* app state */ },\n  onPayment: (eventData, appState, setAppState) =\u003e {\n    // Handle successful payments\n  }\n};\n\nexport default createOICApp(metadata, appContent);\n```\n\n#### Real-time Event System\n- Socket.io server monitoring Circles RPC for blockchain events\n- Automatic client updates on payment confirmations\n- Event filtering and routing to appropriate apps\n\n#### Payment Flow\n1. User initiates action requiring payment\n2. QR code generated with recipient address and amount\n3. User scans and pays via mobile wallet\n4. Blockchain event detected by monitoring system\n5. Payment verified and app state updated\n6. User sees immediate confirmation and results\n\n## 🚀 Deployment\n\nThe OIC Framework supports multiple deployment strategies:\n\n### Option 1: DigitalOcean App Platform (Recommended)\n- **Pros**: Zero server management, auto-scaling, built-in CI/CD\n- **Cost**: $5-12/month\n- **Setup**: Connect GitHub repo, configure environment variables, deploy\n\n### Option 2: Self-hosted with Docker\n- **Pros**: Full control, cost-effective, flexible configuration\n- **Cost**: $4-6/month for basic VPS\n- **Setup**: Use provided Docker Compose configuration\n\nFor detailed deployment instructions, see [DEPLOYMENT.md](./DEPLOYMENT.md).\n\n## 🛠️ Development\n\n### Creating New Apps\n\n1. **Create app file**\n   ```bash\n   touch pages/apps/my-new-app.js\n   ```\n\n2. **Define app metadata and content**\n   ```javascript\n   import { createOICApp } from \"../../lib/oic-framework\";\n\n   const metadata = {\n     appId: \"my-new-app\",\n     title: \"My New App\",\n     description: \"Description of what it does\",\n     recipient: \"0x...\",\n     initialState: {\n       // Define your app's initial state\n     },\n     onPayment: (eventData, appState, setAppState) =\u003e {\n       // Handle payment confirmations\n     }\n   };\n\n   const appContent = ({ appState, setAppState, generateQR }) =\u003e (\n     \u003cdiv\u003e\n       {/* Your app UI here */}\n     \u003c/div\u003e\n   );\n\n   export default createOICApp(metadata, appContent);\n   ```\n\n3. **Add to navigation**\n   Update `pages/index.js` to include your new app in the APPS array.\n\n### Framework API\n\n#### Core Hooks and Functions\n- `appState` / `setAppState`: React state management\n- `currentAmount` / `setCurrentAmount`: Payment amount handling\n- `generateQR(amount, recipient)`: Generate payment QR codes\n- `onPayment(eventData, ...)`: Payment event handler\n\n#### Event Data Structure\n```javascript\n{\n  transactionHash: \"0x...\",\n  blockNumber: 12345,\n  sender: \"0x...\",\n  recipient: \"0x...\",\n  amount: \"1000000000000000000\", // Wei amount\n  timestamp: \"2024-01-01T12:00:00Z\"\n}\n```\n\n## 🔧 Environment Configuration\n\n### Required Variables\n```bash\n# Circles RPC endpoint for blockchain event polling\nCIRCLES_RPC_URL=https://rpc.circlesubi.network/\n\n# Supabase configuration (needed for social feed persistence)\n# -- this is optional and only required to use the social feed app!!!\nSUPABASE_URL=https://your-project-id.supabase.co\nSUPABASE_ANON_KEY=your-anon-key\nSUPABASE_SERVICE_ROLE_KEY=your-service-role-key\nNEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co\nNEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key\n\n# Application Configuration\nNODE_ENV=development\nNEXT_PUBLIC_APP_URL=http://localhost:3000\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! The OIC Framework is designed to be extensible and community-driven.\n\nOnce you have an app you'd like to list on the page, simply create a PR and one of the team members will be in touch.\n\n## ⚖️ License\n\nThis project is open source and available under the [MIT License](./LICENSE).\n\n---\n\n**Ready to build the future of decentralized applications?** 🚀\n\nStart by exploring the example apps, then create your own innovative token-based applications using the OIC Framework. The possibilities are endless!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faboutcircles%2Foic_apps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faboutcircles%2Foic_apps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faboutcircles%2Foic_apps/lists"}