{"id":32780317,"url":"https://github.com/darkresearch/mallory","last_synced_at":"2025-11-04T18:02:03.906Z","repository":{"id":320513494,"uuid":"1082163291","full_name":"darkresearch/mallory","owner":"darkresearch","description":"Opinionated React Native crypto x AI chat app boilerplate with embedded wallet support, conversational AI, and dynamic UI component injection","archived":false,"fork":false,"pushed_at":"2025-10-31T08:39:46.000Z","size":2408,"stargazers_count":23,"open_issues_count":3,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-31T09:07:42.402Z","etag":null,"topics":["ai-sdk","expo","grid","react-native","squads-protocol","supabase","x402"],"latest_commit_sha":null,"homepage":"https://mallory.fun","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/darkresearch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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-10-23T20:35:17.000Z","updated_at":"2025-10-31T04:57:26.000Z","dependencies_parsed_at":"2025-10-24T08:36:38.806Z","dependency_job_id":null,"html_url":"https://github.com/darkresearch/mallory","commit_stats":null,"previous_names":["darkresearch/mallory"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/darkresearch/mallory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkresearch%2Fmallory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkresearch%2Fmallory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkresearch%2Fmallory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkresearch%2Fmallory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darkresearch","download_url":"https://codeload.github.com/darkresearch/mallory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkresearch%2Fmallory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282686005,"owners_count":26710245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-04T02:00:05.887Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-sdk","expo","grid","react-native","squads-protocol","supabase","x402"],"created_at":"2025-11-04T18:01:00.939Z","updated_at":"2025-11-04T18:02:03.882Z","avatar_url":"https://github.com/darkresearch.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mallory\n\nOpinionated React Native crypto x AI chat app boilerplate with embedded wallet support, conversational AI, and dynamic UI component injection.\n\n## 🏗️ Monorepo Structure\n\n```\nmallory/\n├── apps/\n│   ├── client/          # React Native app (iOS, Android, Web)\n│   └── server/          # Backend API (Node.js + Express)\n├── packages/\n│   └── shared/          # Shared types and utilities\n└── package.json         # Workspace configuration\n```\n\n## ✨ Features\n\n### Client (Mobile \u0026 Web)\n- 🔐 **Authentication**: Google OAuth via Supabase\n- 💬 **AI Chat**: Streaming conversations with Claude\n- 💰 **Embedded Wallet**: Grid-powered smart contract wallets\n- 🔑 **Client-Side Signing**: Secure transaction signing (keys never leave device)\n- 📱 **Cross-Platform**: iOS, Android, and Web from single codebase\n- 🎨 **Modern UI**: Beautiful, responsive design with Reanimated\n- 🏷️ **Version Tracking**: Automatic version display with git commit hash\n\n### Server (Backend API)\n- 🤖 **AI Streaming**: Claude integration with Server-Sent Events and extended thinking\n- 🔧 **AI Tools**: Web search (Exa), user memory (Supermemory), and 20+ Nansen data APIs\n- 💰 **x402 Payments**: Server-side implementation for premium data access\n- 💎 **Wallet Data**: Price enrichment via Birdeye API\n- 🔒 **Secure Auth**: Supabase JWT validation\n- 🚀 **Production Ready**: Comprehensive testing infrastructure\n\n### Monorepo Management\n- 🔄 **Synchronized Versioning**: Single command updates all packages\n- 🏷️ **Automatic Releases**: GitHub releases created on version tags\n- 📝 **Generated Changelogs**: Commit history automatically compiled\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Node.js 18+ or Bun\n- Git\n- Expo CLI (optional, included in dependencies)\n\n### 1. Clone and Install\n\n```bash\ngit clone https://github.com/darkresearch/mallory.git\ncd mallory\nbun install\n```\n\n### 2. Environment Setup\n\n#### Client Environment (`.env` in `apps/client/`)\n```bash\n# Copy from template\ncp apps/client/.env.example apps/client/.env\n\n# Required variables:\nEXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co\nEXPO_PUBLIC_SUPABASE_ANON_KEY=your-anon-key\nEXPO_PUBLIC_BACKEND_API_URL=http://localhost:3001\nEXPO_PUBLIC_GRID_API_KEY=your-grid-api-key\nEXPO_PUBLIC_GRID_ENV=sandbox\n```\n\n#### Server Environment (`.env` in `apps/server/`)\n```bash\n# Copy from template\ncp apps/server/.env.example apps/server/.env\n\n# Required variables:\nSUPABASE_URL=https://your-project.supabase.co\nSUPABASE_SERVICE_ROLE_KEY=your-service-role-key\nANTHROPIC_API_KEY=sk-ant-your-key\nBIRDEYE_API_KEY=your-birdeye-key\nGRID_API_KEY=your-grid-api-key\n\n# Optional (for AI tools):\nEXA_API_KEY=your-exa-key\nSUPERMEMORY_API_KEY=your-supermemory-key\n```\n\n### 3. Run Development Servers\n\n#### Option A: Run Both (Client + Server)\n```bash\nbun run dev\n```\n\n#### Option B: Run Separately\n```bash\n# Terminal 1 - Backend\nbun run server\n\n# Terminal 2 - Client (Web)\nbun run client\n```\n\nThe client will be available at:\n- Web: http://localhost:8081\n- API: http://localhost:3001\n\n## 📱 Client Development\n\nSee [apps/client/README.md](./apps/client/README.md) for detailed client documentation.\n\n**Key Commands:**\n```bash\ncd apps/client\n\n# Web\nbun run web\n\n# iOS (requires Mac + Xcode)\nbun run ios\n\n# Android (requires Android Studio)\nbun run android\n```\n\n## 🔧 Server Development\n\nSee [apps/server/README.md](./apps/server/README.md) for detailed server documentation.\n\n**API Endpoints:**\n- `POST /api/chat` - AI chat streaming with tool calling\n- `GET /api/wallet/holdings` - Wallet holdings with price data\n- `GET /health` - Health check\n\n**AI Tools:**\n- `searchWeb` - Web search via Exa (always available)\n- `addMemory` - User memory via Supermemory (optional)\n- `nansen*` - 20+ Nansen API endpoints for blockchain analytics (requires x402 payments)\n\n## 🔑 Grid Wallet Integration\n\nMallory uses [Grid](https://developers.squads.so) for embedded wallets:\n\n- **Non-Custodial**: User private keys never exist - Grid uses secure enclaves and MPC\n- **Email-Based Auth**: Simple OTP verification flow\n- **Session Secrets**: Generated client-side, passed to backend only when needed for signing\n- **Smart Contract Wallets**: Spending limits and programmable transactions\n- **Production Ready**: Sandbox and production environments\n- **x402 Integration**: Automatic micropayments for premium data APIs\n\nGrid's architecture means neither the client nor server ever has access to user private keys, making it truly non-custodial while still providing seamless transaction signing.\n\n## 📦 Shared Package\n\nThe `packages/shared` directory contains TypeScript types and utilities shared between client and server:\n\n```typescript\nimport type { ChatRequest, HoldingsResponse } from '@darkresearch/mallory-shared';\nimport { X402PaymentService } from '@darkresearch/mallory-shared';\n```\n\n## 🧪 Testing\n\nMallory has comprehensive test coverage: unit tests, integration tests, and E2E tests.\n\n**Run tests:**\n```bash\ncd apps/client\n\n# Fast tests (unit + integration)\nbun test\n\n# E2E tests (requires backend running)\nbun run test:e2e\n\n# AI-powered tests (optional - expensive)\n# These use Claude to verify response completeness and test 200k+ token conversations\nbun test __tests__/e2e/chat-message-flow.test.ts  # ~5-10 min, ~$1-2\nbun test __tests__/e2e/long-context.test.ts       # ~10-20 min, ~$2-3\n```\n\n**CI/CD:**\n- Regular tests run on every PR\n- AI tests only run when `[run-ai-tests]` is in commit message:\n  ```bash\n  git commit -m \"fix: improve streaming [run-ai-tests]\"\n  ```\n\nSee [apps/client/__tests__/CHAT_STATE_TESTS.md](./apps/client/__tests__/CHAT_STATE_TESTS.md) for full testing documentation.\n\n## 🚢 Deployment\n\n### Client Deployment\n- **Web**: Deploy to Vercel, Netlify, or any static host\n- **iOS**: Deploy via Expo EAS or native build\n- **Android**: Deploy via Expo EAS or native build\n\nSee [apps/client/README.md](./apps/client/README.md#deployment) for details.\n\n### Server Deployment\n- **Recommended**: Railway, Render, Fly.io\n- **Node.js**: Any Node.js 18+ hosting\n\nSee [apps/server/README.md](./apps/server/README.md#deployment) for details.\n\n## 🏷️ Version Management\n\nMallory uses synchronized semantic versioning across all packages.\n\n### Auto-Release via PR\n\nInclude `[release: v*.*.*]` in your PR title:\n\n```\nfeat: add new wallet feature [release: v0.2.0]\n```\n\nWhen merged to `main`, the version automatically bumps and a GitHub release is created! 🚀\n\n### Manual Release\n\n```bash\nbun scripts/sync-version.js 0.2.0\ngit add . \u0026\u0026 git commit -m \"chore: bump version to 0.2.0\"\ngit tag v0.2.0 \u0026\u0026 git push \u0026\u0026 git push --tags\n```\n\nSee [VERSION.md](./VERSION.md) for details.\n\n## 🤝 Contributing\n\nContributions welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) first.\n\n## 📄 License\n\nApache License 2.0 - see [LICENSE](./LICENSE) for details.\n\n## 🆘 Support\n\n- 📧 Email: hello@darkresearch.ai\n- 🐛 Issues: [GitHub Issues](https://github.com/darkresearch/mallory/issues)\n- 📚 Docs: [Full Documentation](./docs/)\n\n## 🙏 Acknowledgments\n\nBuilt with:\n- [Expo](https://expo.dev) - React Native framework\n- [Grid (Squads)](https://developers.squads.so) - Embedded wallets\n- [Anthropic](https://anthropic.com) - Claude AI with extended thinking\n- [Exa](https://exa.ai) - AI-powered web search\n- [Supermemory](https://supermemory.ai) - User memory \u0026 RAG\n- [Supabase](https://supabase.com) - Auth \u0026 database\n- [Birdeye](https://birdeye.so) - Solana market data\n- [Nansen](https://nansen.ai) - Blockchain analytics (via x402)\n- [Faremeter](https://x402.org) - x402 payment protocol\n- [streamdown-rn](https://www.npmjs.com/package/streamdown-rn) - React Native markdown streaming\n\n---\n\n**Made with ❤️ by [Dark](https://darkresearch.ai)**\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkresearch%2Fmallory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarkresearch%2Fmallory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkresearch%2Fmallory/lists"}