{"id":35278387,"url":"https://github.com/basantsd/circlesettle","last_synced_at":"2026-05-21T02:01:53.462Z","repository":{"id":319607206,"uuid":"1074803524","full_name":"basantsd/circlesettle","owner":"basantsd","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-25T20:31:04.000Z","size":2788,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-03T02:52:20.437Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://circlesettle.vercel.app","language":"Solidity","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/basantsd.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-10-12T14:07:43.000Z","updated_at":"2025-10-25T20:37:21.000Z","dependencies_parsed_at":"2025-10-19T18:12:12.773Z","dependency_job_id":"2088b4a3-d55d-4dd6-9158-f4f13f35b903","html_url":"https://github.com/basantsd/circlesettle","commit_stats":null,"previous_names":["basantsd/circlesettle"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/basantsd/circlesettle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basantsd%2Fcirclesettle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basantsd%2Fcirclesettle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basantsd%2Fcirclesettle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basantsd%2Fcirclesettle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basantsd","download_url":"https://codeload.github.com/basantsd/circlesettle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basantsd%2Fcirclesettle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33284880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-20T15:12:43.734Z","status":"online","status_checked_at":"2026-05-21T02:00:07.181Z","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":[],"created_at":"2025-12-30T14:08:07.760Z","updated_at":"2026-05-21T02:01:53.456Z","avatar_url":"https://github.com/basantsd.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CircleSettle 💫\n\n**Fair bill splitting, built on trust.**\n\nCircleSettle is a Web3-powered bill-splitting app with AI receipt scanning, voice commands, and an on-chain credit score system. Split bills fairly with friends and build your financial reputation in the process.\n\n---\n\n## 🌟 Key Features\n\n### 1. AI-Powered Receipt Scanning 🤖\n- **Upload any receipt** - Camera or file upload\n- **Automatic extraction** - Items, prices, tax, tip\n- **Multi-currency support** - USD, INR, EUR, GBP, JPY, AUD, CAD\n- **Powered by ASI:One** - Advanced OCR with AI\n\n### 2. Multi-Person Bill Splitting 👥\n- **Add multiple friends** - Split with 2, 3, 4+ people\n- **Custom amounts** - Manual entry for each person's share\n- **Auto-fill remaining** - Automatically calculate last person's amount\n- **Smart validation** - Ensures amounts add up correctly\n\n### 3. Circle Score - On-Chain Credit 💳\n- **Transparent scoring** - 300-850 range (like FICO)\n- **Automatic updates** - Every action impacts your score\n- **Borrowing power** - Higher score = more loan eligibility\n- **Scoring rules:**\n  - ✅ Split a bill: **+5 points**\n  - ✅ Pay within 24 hours: **+10 points**\n  - ✅ Repay a loan: **+50 points**\n  - ❌ Late payment: **-50 points**\n\n### 4. Cross-Chain Payments 🌐\n- **Avail Nexus** - Cross-chain infrastructure\n- **Multi-network** - Split bills across any chain\n- **USDC settlements** - Stable, reliable payments\n\n---\n\n## 🎯 How It Works\n\n### User Flow\n\n```\n1. Connect Wallet (RainbowKit)\n   ↓\n2. Choose Split Method:\n   - Manual Split: Enter total bill and friends' shares\n   - AI Scanner: Upload receipt photo\n   ↓\n3. Add Multiple Friends (4-5+ people)\n   ↓\n4. Enter Amount Each Friend Owes (or auto-fill remaining)\n   ↓\n5. Create Debt Records On-Chain\n   ↓\n6. Circle Score +5 (both parties)\n   ↓\n7. Settle Payment (within 24h = +10 pts)\n   ↓\n8. Build Reputation → Unlock Loans\n```\n\n---\n\n## 📊 System Diagrams\n\n### System Architecture\n![System Architecture](docs/images/architecture-diagram.png)\n\n### User Flow\n![User Flow](docs/images/user-flow-diagram.png)\n\n### Technical Sequence\n![Technical Sequence](docs/images/technical-sequence-diagram.png)\n\n---\n\n## 🏗️ Architecture\n\n### Tech Stack\n\n**Frontend:**\n- **Next.js 15** - React framework with App Router\n- **TypeScript** - Type-safe development\n- **TailwindCSS 4** - Utility-first styling\n- **Wagmi** - Ethereum React hooks\n- **RainbowKit** - Beautiful wallet connection\n- **Lucide React** - Professional icon library\n\n**Smart Contracts:**\n- **Solidity 0.8.20** - Smart contract language\n- **Foundry** - Development \u0026 testing framework\n- **OpenZeppelin** - Security standards\n\n**AI/ML:**\n- **ASI:One API** - Receipt OCR (primary)\n\n**Blockchain:**\n- **Avail Nexus** - Cross-chain messaging\n- **Ethereum-compatible chains** - Primary deployment\n- **USDC** - Payment token\n\n---\n\n## 📁 Project Structure\n\n```\ncirclesettle/\n├── app/\n│   ├── page.tsx                    # Landing page\n│   ├── dashboard/page.tsx          # Main dashboard\n│   ├── split-bill/page.tsx         # Manual split\n│   ├── split-bill-ai/page.tsx      # AI scanner + voice\n│   └── api/scan-receipt/route.ts   # OCR API endpoint\n├── components/\n│   ├── CircleScoreCard.tsx         # Score display\n│   ├── PaymentHistoryTimeline.tsx  # Activity timeline with filters\n│   ├── ScoreTrendGraph.tsx         # Score visualization\n│   ├── DebtCard.tsx                # Transaction card\n│   ├── Header.tsx                  # Navigation header\n│   └── CrossChainBanner.tsx        # Network selector\n├── contracts/\n│   ├── src/\n│   │   ├── CircleScore.sol         # Credit scoring\n│   │   └── MicroDebtTracker.sol    # Debt tracking\n│   ├── test/\n│   │   └── CircleScore.t.sol       # Contract tests\n│   └── script/\n│       └── DeployCircleScore.s.sol # Deployment\n├── lib/\n│   ├── hooks/\n│   │   ├── useCircleScore.ts       # Score data hook\n│   │   ├── useDebts.ts             # Debt queries\n│   │   └── useAddDebt.ts           # Create debt\n│   └── contracts/\n│       └── CircleScoreABI.ts       # Contract ABI\n└── .env.example                     # Environment template\n```\n\n---\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- **Node.js 18+** - JavaScript runtime\n- **npm/yarn/pnpm** - Package manager\n- **Foundry** - Smart contract toolchain\n- **Wallet** - MetaMask or compatible\n\n### Installation\n\n1. **Clone the repository**\n```bash\ngit clone https://github.com/yourusername/circlesettle.git\ncd circlesettle\n```\n\n2. **Install dependencies**\n```bash\nnpm install\n```\n\n3. **Set up environment variables**\n```bash\ncp .env.example .env.local\n```\n\nEdit `.env.local` with your keys:\n```env\nHEDERA_ACCOUNT_ID=0.0.7xxxxxx\nHEDERA_PRIVATE_KEY=0x0000000000000000000000000000000000000000\nNEXT_PUBLIC_HEDERA_TESTNET_RPC=https://testnet.hashio.io/api\nWALLETCONNECT_PROJECT_ID=your_project_id_here\nNODE_ENV=\"development\"\nNEXT_PUBLIC_USE_TESTNET=true\nASI_ONE_API_KEY=sk_40000000000000000000000000000000000000000\n\n```\n\n4. **Run development server**\n```bash\nnpm run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000)\n\n---\n\n## 📜 Smart Contract Deployment\n\n### 1. Install Foundry\n```bash\ncurl -L https://foundry.paradigm.xyz | bash\nfoundryup\n```\n\n### 2. Build Contracts\n```bash\ncd contracts\nforge build\n```\n\n### 3. Run Tests\n```bash\nforge test -vv\n```\n\n### 4. Deploy to Testnet\n```bash\n# Set your private key in .env\necho \"PRIVATE_KEY=your_private_key\" \u003e\u003e .env\n\n# Deploy CircleScore + MicroDebtTracker\nforge script script/DeployCircleScore.s.sol \\\n  --rpc-url \u003cYOUR_RPC_URL\u003e \\\n  --broadcast \\\n  --verify\n```\n\n### 5. Update Frontend Config\nCopy deployed addresses to `.env.local`:\n```env\nNEXT_PUBLIC_CIRCLE_SCORE_ADDRESS=0x...\nNEXT_PUBLIC_DEBT_TRACKER_ADDRESS=0x...\n```\n\n---\n\n## 🎮 Usage Guide\n\n### 1. Connect Your Wallet\n- Click \"Connect Wallet\" button\n- Select MetaMask (or other wallet)\n- Approve connection\n\n### 2. Split a Bill with AI\n- Navigate to \"AI Scanner\"\n- Upload receipt photo\n- Wait for AI to extract items\n- Select the items you had\n- Review your calculated share\n- Add multiple friends' wallet addresses\n- Enter amount each friend owes (or use auto-fill)\n- Click \"Create Debt Records\"\n- Approve transactions in wallet\n\n### 3. View Your Circle Score\n- Dashboard shows your score prominently\n- Hover over stats for tooltips\n- View score trend graph (always shows at least 2 points)\n- Check payment history timeline with filters:\n  - Filter by type (All, Bills Split, Paid, Received)\n  - Search by address or amount\n  - Sort by date or amount\n  - Click blockchain explorer links for transaction details\n- See borrowing power\n\n### 4. Settle a Debt\n- Find debt in \"Your Transactions\"\n- Click \"Settle\" button\n- Approve payment\n- Score updates automatically:\n  - Within 24 hours: **+10 points** ✅\n  - After 24 hours: **-50 points** ⚠️\n\n---\n\n## 🧪 Testing\n\n### Frontend Tests\n```bash\nnpm run test\n```\n\n### Smart Contract Tests\n```bash\ncd contracts\nforge test -vv\n\n# Run specific test\nforge test --match-test testRecordBillSplit -vvv\n\n# Gas report\nforge test --gas-report\n```\n\n### Test Coverage\n```bash\nforge coverage\n```\n\n---\n\n## 🎨 Features Breakdown\n\n### CircleScore Smart Contract\n\n#### Core Functions\n```solidity\n// View functions\ngetScore(address user) → uint256\ngetScoreDetails(address user) → UserScore\ncalculateBorrowingPower(address user) → uint256\nisEligibleForLoan(address user, uint256 amount) → bool\n\n// State-changing functions\nrecordBillSplit(address user)        // +5 points\nrecordPayment(address user, uint256 debtTime)  // +10 or -50\nrecordLoanRepayment(address user)    // +50 points\n```\n\n#### Scoring Algorithm\n```javascript\nInitial Score: 500\n\nBill Split: +5\n  → Total: 500 + 5 = 505\n\nOn-Time Payment (\u003c 24h): +10\n  → Total: 505 + 10 = 515\n\nLate Payment (\u003e 24h): -50\n  → Total: 515 - 50 = 465\n\nLoan Repaid: +50\n  → Total: 465 + 50 = 515\n\nMin: 300, Max: 850\n```\n\n#### Borrowing Power Formula\n```javascript\nif (score \u003c 500) return 0\nif (score \u003e= 850) return $5,000\nif (score \u003e= 700) return $1,000 + (score - 700) * $26.67\nif (score \u003e= 500) return $200 + (score - 500) * $4.00\n\nExample:\n- Score 500 → $200\n- Score 600 → $600\n- Score 700 → $1,000\n- Score 750 → $2,333\n- Score 850 → $5,000\n```\n\n---\n\n## 🔐 Security\n\n### Smart Contract Security\n- **Audited patterns** - OpenZeppelin standards\n- **Reentrancy protection** - Checks-effects-interactions\n- **Access control** - Only debtor can settle their debt\n- **Integer overflow** - Solidity 0.8.20 built-in protection\n- **Score bounds** - Clamped to 300-850 range\n\n### Frontend Security\n- **Environment variables** - API keys never exposed\n- **Wallet signatures** - User authorization required\n- **Input validation** - Form validation on all inputs\n- **HTTPS only** - Secure connections enforced\n\n---\n\n## 🏆 Hackathon Integration\n\n### Partner Technologies\n\n#### 1. ASI Alliance (ASI:One)\n- **Receipt OCR** - Primary scanning engine\n- **High accuracy** - Item extraction with AI\n- **Multi-language** - Supports international receipts\n- **API Integration** - `api/scan-receipt/route.ts`\n\n#### 2. Avail Nexus\n- **Cross-chain messaging** - Multi-network support\n- **USDC transfers** - Stable payment routing\n- **SDK Integration** - `lib/avail-config.ts`\n- **Network switching** - ChainSelector component\n\n#### 3. Hedera (Future)\n- **Fast finality** - Sub-second transactions\n- **Low fees** - Cost-effective settlements\n- **HCS** - Consensus service for disputes\n\n---\n\n## 📊 Metrics \u0026 Analytics\n\n### Smart Contract Events\n```solidity\nevent DebtCreated(uint256 debtId, address creditor, address debtor, uint256 amount)\nevent DebtSettled(uint256 debtId)\nevent ScoreUpdated(address user, uint256 newScore, string reason)\nevent BillSplitRecorded(address user, uint256 scoreIncrease)\nevent PaymentRecorded(address user, bool onTime, uint256 scoreChange)\n```\n\n### Track User Activity\n- Total debts created\n- Average settlement time\n- Score distribution\n- Borrowing power trends\n- Payment success rate\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. **Fork the repository**\n2. **Create a feature branch** (`git checkout -b feature/AmazingFeature`)\n3. **Commit your changes** (`git commit -m 'feat: add amazing feature'`)\n4. **Push to the branch** (`git push origin feature/AmazingFeature`)\n5. **Open a Pull Request**\n\n### Commit Convention\n- `feat:` - New feature\n- `fix:` - Bug fix\n- `refactor:` - Code refactoring\n- `ui:` - UI/UX changes\n- `test:` - Adding tests\n- `chore:` - Maintenance tasks\n\n---\n\n## 📝 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 👨‍💻 Author\n\n**Basant Singh**\n\nBuilt for ETH Online 2025 with ❤️\n\n---\n\n## 🙏 Acknowledgments\n\n- **ASI Alliance** - AI-powered receipt scanning\n- **Avail Project** - Cross-chain infrastructure\n- **OpenZeppelin** - Secure smart contract libraries\n- **Wagmi Team** - Excellent React hooks\n- **RainbowKit** - Beautiful wallet UX\n\n---\n\n## 📞 Support\n\n- **Issues:** [GitHub Issues](https://github.com/basantsd/circlesettle/issues)\n- **Linkedin:** [@basantsd](https://www.linkedin.com/in/basantsd/)\n- **Email:** sbasant12345@gmail.com\n\n---\n\n## ⚠️ Disclaimer\n\nCircleSettle is a hackathon project and currently in beta. Smart contracts have not been professionally audited. Use at your own risk. Do not use with significant amounts of cryptocurrency on mainnet.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[Website](https://circlesettle.com)** • **[Demo Video](https://youtube.com/watch?v=...)**\n\nMade with 💫 for the future of trust-based finance\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasantsd%2Fcirclesettle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasantsd%2Fcirclesettle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasantsd%2Fcirclesettle/lists"}