{"id":29872312,"url":"https://github.com/chaoschain/fin-studio","last_synced_at":"2025-07-30T20:10:09.674Z","repository":{"id":306920818,"uuid":"1019433902","full_name":"ChaosChain/fin-studio","owner":"ChaosChain","description":"A modern fintech analysis platform powered by AI agents using Google's A2A (Agent-to-Agent) protocol for seamless communication and collaboration, with integrated blockchain systems.","archived":false,"fork":false,"pushed_at":"2025-07-28T11:33:28.000Z","size":1265,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-28T13:24:22.745Z","etag":null,"topics":["a2a","agents","finance-studio","llm"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChaosChain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/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}},"created_at":"2025-07-14T10:14:01.000Z","updated_at":"2025-07-28T11:33:32.000Z","dependencies_parsed_at":"2025-07-28T13:34:32.670Z","dependency_job_id":null,"html_url":"https://github.com/ChaosChain/fin-studio","commit_stats":null,"previous_names":["chaoschain/fin-studio"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ChaosChain/fin-studio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChaosChain%2Ffin-studio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChaosChain%2Ffin-studio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChaosChain%2Ffin-studio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChaosChain%2Ffin-studio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChaosChain","download_url":"https://codeload.github.com/ChaosChain/fin-studio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChaosChain%2Ffin-studio/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267931424,"owners_count":24167612,"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-07-30T02:00:09.044Z","response_time":70,"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":["a2a","agents","finance-studio","llm"],"created_at":"2025-07-30T20:10:05.481Z","updated_at":"2025-07-30T20:10:09.660Z","avatar_url":"https://github.com/ChaosChain.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ChaosChain + Google A2A Protocol - AI-Powered Investment Research Platform\n\nChaosChain is a modern, open source fintech platform that leverages Google's official A2A (Agent-to-Agent) SDK and blockchain payment systems to deliver comprehensive investment research and analysis. The platform demonstrates the complete ChaosChain workflow powered by Google's official A2A Protocol, featuring agent discovery, JSON-RPC communication, DKG, verifier networks, consensus, and on-chain payments.\n\n---\n\n## Overview\n\nChaosChain combines multi-agent AI analysis with Google's official A2A Protocol for seamless agent communication. Specialized AI agents communicate using Google's A2A SDK with JSON-RPC messaging, providing real-time market insights, technical analysis, macroeconomic research, and comprehensive investment analysis. The platform integrates DKG (Distributed Knowledge Graph), verifier networks, consensus mechanisms, and blockchain payments for a complete decentralized AI workflow.\n\n### Key Features\n\n- **Google A2A Protocol**: Official A2A SDK with JSON-RPC 2.0 messaging\n- **Multi-Agent AI System**: 16 specialized, collaborative AI agents (GPT-4 variants)\n- **DKG Integration**: Distributed Knowledge Graph with Proof of Agency\n- **Verifier Network**: 4 independent verifiers with consensus validation\n- **Agent Reputation Network (ARN)**: Decentralized agent discovery and coordination\n- **Blockchain Payments**: Integrated x402 and Commerce Payments with micro-transactions\n- **Real-Time Analysis**: Live market data and AI-powered insights\n- **ChaosChain Workflow**: Complete decentralized AI agent workflow\n- **Modern UI**: Responsive Next.js frontend with A2A protocol indicators\n\n## AI Agents with A2A Protocol\n\nThe platform features 16 specialized AI agents that communicate via Google's official A2A SDK:\n\n### **Core Financial Agents (GPT-4 variants)**\n- **Market Research Agents** (GPT-4, GPT-4o): Market sentiment, news analysis, trend research\n- **Macro Research Agents** (GPT-4, GPT-4o): Economic indicators, central bank policies, global trends  \n- **Price Analysis Agents** (GPT-4, GPT-4o): Technical analysis, chart patterns, price predictions\n- **Insights Agents** (GPT-4, GPT-4o): Report generation, cross-agent analysis, recommendations\n\n### **Verification Network**\n- **Verifier Agents 1-4**: Independent verification, consensus validation, multi-criteria scoring\n\n### **A2A Protocol Features**\n- **Agent Discovery**: JSON-RPC `agent/discover` calls\n- **Task Distribution**: A2A `message/send` protocol  \n- **Data Sharing**: Inter-agent `data/share` communication\n- **DKG Integration**: `dkg/create_node` with Proof of Agency\n\n## Payment Systems\n\n- **x402 Protocol**: HTTP-native payment protocol for micro-payments (Base Sepolia testnet \u0026 Base Mainnet)\n- **Commerce Payments Protocol**: On-chain \"authorize and capture\" payment flows with escrow and flexible fees (Base network)\n\n## Prerequisites\n\n- **Node.js**: 18+\n- **Package Manager**: yarn (recommended) or npm\n- **OpenAI API Key**: Required for AI analysis\n- **Google A2A SDK**: `@a2a-js/sdk` (installed automatically)\n- **Blockchain Wallet**: For payment testing (optional)\n\n## Quick Start\n\n1. **Clone the Repository**\n   ```bash\n   git clone https://github.com/ChaosChain/fin-studio\n   cd fin-studio\n   ```\n2. **Install Dependencies**\n   ```bash\n   yarn install\n   ```\n3. **Environment Setup**\n   - Copy the example environment file:\n     ```bash\n     cp env.local.example .env.local\n     ```\n   - Configure your environment variables in `.env.local`:\n     ```env\n     OPENAI_API_KEY=your_openai_api_key_here\n     AGENT_MANAGER_PORT=8080\n     NETWORK=base-sepolia\n     OPERATOR_ADDRESS=0x0000000000000000000000000000000000000000\n     OPERATOR_PRIVATE_KEY=0x0000000000000000000000000000000000000000000000000000000000000000\n     FACILITATOR_URL=https://x402.org/facilitator\n     ESCROW_CONTRACT_ADDRESS=0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff\n     DEVELOPMENT_MODE=true\n     BASE_SEPOLIA_RPC_URL=https://sepolia.base.org\n     ```\n4. **Build the Application**\n   ```bash\n   yarn agents:build      # Build AI agents with A2A support\n   ```\n   \u003e For payment testing, you may need ETH from the [Base Sepolia Faucet](https://www.alchemy.com/faucets/base-sepolia) and USDC from [Circle Faucet](https://faucet.circle.com/).\n\n5. **Start the Services** (in separate terminals):\n   - **AI Agents with A2A Protocol**\n     ```bash\n     yarn agents:start\n     ```\n     Starts all 16 AI agents with Google A2A SDK integration\n   - **Frontend with A2A Integration**\n     ```bash\n     yarn dev\n     ```\n     Starts the Next.js frontend with integrated A2A protocol (port 3000)\n\n6. **Access the Application**\n   - **ChaosChain + A2A Demo**: [http://localhost:3000/chaos-demo](http://localhost:3000/chaos-demo)\n   - Main Dashboard: [http://localhost:3000](http://localhost:3000)\n   - Agent Dashboard: [http://localhost:3000/dashboard](http://localhost:3000/dashboard)\n\n## Documentation\n\nFor technical architecture and further details, see [docs/TECHNICAL_ARCHITECTURE.md](docs/TECHNICAL_ARCHITECTURE.md).\n\n## Tech Stack\n\n**Frontend**: Next.js 14 (App Router), TypeScript, Tailwind CSS, Radix UI, Recharts, jsPDF  \n**A2A Protocol**: Google's official `@a2a-js/sdk`, JSON-RPC 2.0 messaging  \n**Backend**: Node.js, Express, OpenAI GPT-4 API, DKG, ARN, Verifier Network  \n**Blockchain**: Base Sepolia/Mainnet, x402, Commerce Payments, viem, wagmi\n\n## Project Structure\n\n```\nfin-studio/\n├── src/\n│   ├── app/\n│   │   └── chaos-demo/        # ChaosChain + A2A Protocol Demo\n│   ├── components/\n│   │   ├── ChaosChainDemo.tsx # Main demo with A2A integration\n│   │   ├── DKGVisualizer.tsx  # Distributed Knowledge Graph\n│   │   ├── VerifierNetworkVisualizer.tsx # Verifier network\n│   │   └── ui/               # Reusable UI components  \n│   ├── agents/               # 16 AI agents with A2A support\n│   ├── lib/\n│   │   ├── a2a/             # Custom A2A implementation (legacy)\n│   │   ├── payment/         # x402 \u0026 Commerce Payments\n│   │   ├── dkg.ts           # Distributed Knowledge Graph\n│   │   └── agent-relay-network.ts # ARN coordination\n│   ├── types/\n│   │   ├── a2a.ts           # A2A protocol types\n│   │   └── payment.ts       # Payment system types\n│   └── utils/               # Helper utilities\n├── scripts/\n│   └── test-a2a-integration.js # A2A protocol integration tests\n├── tests/                   # A2A validation tests\n├── payment/                 # Payment implementations\n└── docs/                    # Documentation\n```\n\n## Available Scripts\n\n| Script                | Description                                    |\n|-----------------------|------------------------------------------------|\n| `yarn dev`            | Start frontend with A2A protocol integration   |\n| `yarn build`          | Build frontend for production                   |\n| `yarn start`          | Start production frontend server                |\n| `yarn agents:build`   | Compile TypeScript agents with A2A support     |\n| `yarn agents:start`   | Start 16 agents with Google A2A SDK            |\n| `yarn test:a2a`       | Test A2A protocol integration                   |\n| `yarn demo:a2a`       | Show ChaosChain + A2A demo URL                  |\n| `yarn lint`           | Run ESLint                                     |\n| `yarn type-check`     | Run TypeScript type checking                    |\n\n## Google A2A Protocol Integration\n\nThe platform uses Google's official A2A SDK (`@a2a-js/sdk`) for agent communication:\n\n### **A2A Workflow Phases**\n1. **🤖 A2A Agent Discovery**: JSON-RPC `agent/discover` via Google Protocol\n2. **🎯 A2A Task Coordination**: Google A2A SDK coordination\n3. **⚡ A2A Task Distribution**: JSON-RPC `message/send` protocol\n4. **🔬 Real Analysis Execution**: A2A-coordinated agents\n5. **🤝 A2A Inter-Agent Data Sharing**: `data/share` JSON-RPC calls\n6. **🔗 A2A DKG Node Creation**: `dkg/create_node` with Proof of Agency\n7. **💰 A2A Payment Distribution**: Consensus-based payments\n\n### **JSON-RPC 2.0 Compliance**\n- All messages follow official A2A specification\n- Message structure: `{id, jsonrpc: \"2.0\", method, params, timestamp}`\n- Methods: `agent/discover`, `message/send`, `data/share`, `dkg/create_node`\n\n### **Testing A2A Integration**\n```bash\nyarn test:a2a  # Comprehensive A2A protocol validation\n```\n\n## Architecture Overview\n\n```\nFrontend with A2A Protocol → Direct Agent Communication\n         ↓                           ↓\n    Port 3000                 16 AI Agents + ARN\n                              (Google A2A SDK)\n                                     ↓\n            DKG → Verifiers → Consensus → Payments\n```\n\n**Integrated A2A Workflow:**\n- Frontend includes A2A protocol integration\n- Agents communicate via Google's official A2A SDK\n- No separate gateway server needed\n- Complete ChaosChain workflow in one demo\n\n## Payment Integration\n\n### x402 Protocol\n\nHTTP-native payments can be integrated as middleware:\n\n```typescript\napp.use(\n  paymentMiddleware(\"0xYourAddress\", { \n    \"/your-endpoint\": \"$0.01\" \n  })\n);\n```\n\n### Commerce Payments\n\nFor advanced payment flows (authorize and capture):\n\n```typescript\nconst authResult = await authorizePayment(payer, amount, token);\nconst captureResult = await capturePayment(authId, amount);\n```\n\n### Supported Networks\n\n- **Base Sepolia**: Testnet for development\n- **Base Mainnet**: Production network\n\n## ChaosChain Workflow\n\nThe complete ChaosChain workflow integrates Google A2A Protocol with decentralized AI:\n\n### **Phase 1: A2A Agent Discovery**\n- Agents discover each other via Google A2A protocol\n- JSON-RPC `agent/discover` calls identify capabilities\n- ARN (Agent Reputation Network) coordinates agent selection\n\n### **Phase 2: A2A Task Distribution**  \n- Tasks distributed via A2A `message/send` protocol\n- Real-time financial analysis coordinated across 16 agents\n- GPT-4 variants provide specialized analysis\n\n### **Phase 3: A2A Inter-Agent Data Sharing**\n- Agents share data via A2A `data/share` JSON-RPC calls\n- Market → Insights, Price → Insights, Macro → Insights\n- Real analysis data flows between agents\n\n### **Phase 4: DKG \u0026 Proof of Agency**\n- Distributed Knowledge Graph stores agent outputs\n- A2A `dkg/create_node` creates signed nodes\n- Proof of Agency validates agent authenticity\n\n### **Phase 5: Verifier Network \u0026 Consensus**\n- 4 independent verifiers validate all outputs\n- Multi-criteria scoring and consensus calculation\n- Reputation updates based on verification results\n\n### **Phase 6: Payment Distribution**\n- Consensus-based payments to agents\n- Micro-transactions via x402 protocol\n- Agent wallets and payment records tracked\n\n## Development\n\n### Adding New Agents\n\n1. Create a new agent class in `src/agents/`\n2. Implement required interfaces from `src/types/a2a.ts`\n3. Register the agent in `src/agents/manager.ts`\n4. Add port configuration\n\nExample:\n\n```typescript\nexport class CustomAgent {\n  getIdentity(): AgentIdentity {\n    return {\n      id: 'custom-agent',\n      name: 'Custom Agent',\n      type: AgentType.CUSTOM,\n      version: '1.0.0',\n      capabilities: ['custom_analysis']\n    };\n  }\n\n  getHandlers(): Map\u003cstring, A2AHandlerFunction\u003e {\n    const handlers = new Map();\n    handlers.set('custom_action', this.customAction.bind(this));\n    return handlers;\n  }\n\n  private async customAction(message: A2AMessage): Promise\u003cA2AMessage\u003e {\n    // Implementation\n  }\n}\n```\n\n### API Integration\n\n- Obtain an OpenAI API key from [OpenAI Platform](https://platform.openai.com/api-keys)\n- Add it to `.env.local`\n- Monitor usage and costs\n\n### Market Data Sources\n\n- **OpenAI Search**: Real-time market data and news\n- **AI-Powered Analysis**: All analysis via OpenAI GPT-4\n- **Comprehensive Coverage**: Market data, news, economic indicators\n\n## Security\n\n- Store API keys in environment variables\n- Use secure HTTP for A2A communication\n- Validate all agent inputs\n- Implement robust error handling to prevent information leakage\n- Use audited smart contracts for payment systems\n\n## Monitoring and Debugging\n\n- Monitor agent health and metrics via the dashboard\n- Enable debug logging for troubleshooting:\n  ```bash\n  DEBUG=fin-studio:* yarn agents:start\n  ```\n- Track OpenAI API usage and per-agent costs\n\n## Deployment\n\n### Frontend Deployment (Vercel or similar)\n\n```bash\nyarn build\n# Deploy the output to Vercel or your preferred platform\n```\n\n### Agent System Deployment (with A2A)\n\n1. Build agents: `yarn agents:build`\n2. Deploy the `dist/` folder to your server\n3. Set up environment variables (including OpenAI API key)\n4. Start with a process manager: `yarn agents:start`\n5. Verify A2A integration: `yarn test:a2a`\n\n## Contributing\n\nWe welcome contributions to the ChaosChain + Google A2A Protocol project! To maintain high code quality and A2A compliance, please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/your-feature`\n3. Make changes and add tests as appropriate\n4. Ensure all checks pass: `yarn lint \u0026\u0026 yarn type-check \u0026\u0026 yarn test:a2a`\n5. Commit: `git commit -am 'Add your feature'`\n6. Push: `git push origin feature/your-feature`  \n7. Open a Pull Request with a clear description\n\n**A2A Integration Requirements:**\n- All agent communication must use Google A2A SDK\n- JSON-RPC 2.0 compliance required\n- Test A2A integration with `yarn test:a2a`\n\nPlease review the [CONTRIBUTING.md](payment/x402/CONTRIBUTING.md) for more details on our contribution process and code of conduct.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **ChaosChain + A2A Demo**: Visit [http://localhost:3000/chaos-demo](http://localhost:3000/chaos-demo)\n- **A2A Integration Testing**: Run `yarn test:a2a` to verify protocol compliance\n- **Documentation**: See this README and inline code comments\n- **Issues**: Open an issue on GitHub for bugs or feature requests\n- **Discussions**: Use GitHub Discussions for questions and ideas\n\n### **Quick Demo Commands**\n```bash\n# Start the complete ChaosChain + A2A workflow\nyarn dev              # Frontend with A2A integration\nyarn agents:start     # 16 agents with Google A2A SDK\nyarn test:a2a         # Verify A2A protocol integration\nyarn demo:a2a         # Show demo URL\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaoschain%2Ffin-studio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchaoschain%2Ffin-studio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaoschain%2Ffin-studio/lists"}