{"id":31130985,"url":"https://github.com/ivanms1/web3-fullstack","last_synced_at":"2025-09-18T03:10:49.317Z","repository":{"id":305705974,"uuid":"1023666592","full_name":"ivanms1/web3-fullstack","owner":"ivanms1","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-21T15:06:34.000Z","size":1837,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-21T16:41:07.112Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://web3-fullstack-dashboard.vercel.app","language":"TypeScript","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/ivanms1.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}},"created_at":"2025-07-21T14:01:50.000Z","updated_at":"2025-07-21T15:06:38.000Z","dependencies_parsed_at":"2025-07-21T16:51:19.576Z","dependency_job_id":null,"html_url":"https://github.com/ivanms1/web3-fullstack","commit_stats":null,"previous_names":["ivanms1/web3-fullstack"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ivanms1/web3-fullstack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanms1%2Fweb3-fullstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanms1%2Fweb3-fullstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanms1%2Fweb3-fullstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanms1%2Fweb3-fullstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivanms1","download_url":"https://codeload.github.com/ivanms1/web3-fullstack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanms1%2Fweb3-fullstack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275701103,"owners_count":25512259,"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-09-18T02:00:09.552Z","response_time":77,"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-09-18T03:10:45.235Z","updated_at":"2025-09-18T03:10:49.303Z","avatar_url":"https://github.com/ivanms1.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Web3 Fullstack Platform\n\nA comprehensive decentralized financial platform built with Next.js, Solidity smart contracts, and modern web3 technologies. This monorepo includes a financial transaction management system with role-based access control, approval workflows, and a modern React dashboard.\n\n## 🏗️ Architecture\n\nThis is a [Turborepo](https://turborepo.com/) monorepo containing:\n\n### Apps\n\n- **`apps/dashboard`**: Next.js web application with React dashboard\n- **`apps/contracts`**: Solidity smart contracts with Hardhat development environment\n\n### Packages\n\n- **`packages/ui`**: Shared React component library\n- **`packages/eslint-config`**: ESLint configurations\n- **`packages/typescript-config`**: TypeScript configurations\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 18+\n- Yarn package manager\n- **MetaMask wallet extension** (required for frontend app)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone git@github.com:ivanms1/web3-fullstack.git\ncd web3-fullstack\n\n# Install dependencies\nyarn install\n```\n\n### Local Development Setup\n\n**⚠️ Important**: MetaMask is required to run the frontend application. Follow these steps for local development:\n\n#### 1. Start Local Hardhat Node\n\n```bash\ncd apps/contracts\nyarn dev\n```\n\nThis starts a local Hardhat node at `http://localhost:8545`\n\n#### 2. Deploy Contracts Locally\n\nIn a new terminal:\n\n```bash\ncd apps/contracts\nyarn deploy:localhost\n```\n\nThis deploys the smart contracts to your local network and creates test data.\n\n#### 3. Set Up Frontend Environment Variables\n\nAfter deployment, you need to manually move the deployment file and convert it to environment variables:\n\n```bash\n# Copy the deployment file to the dashboard scripts folder\ncp apps/contracts/deployment-info-local.json apps/dashboard/scripts/\n\n# Convert deployment JSON to environment variables\ncd apps/dashboard\nyarn convert-deployment\n```\n\nThis creates a `.env.local` file with the contract addresses and ABIs that the frontend needs.\n\n#### 4. Configure MetaMask for Local Development\n\n**Add Local Network to MetaMask:**\n\n- Open MetaMask\n- Go to Settings → Networks → Add Network\n- Add network manually with these settings:\n  - **Network Name**: Hardhat Local\n  - **RPC URL**: `http://localhost:8545`\n  - **Chain ID**: `31337`\n  - **Currency Symbol**: ETH\n\n**Import Admin Account:**\n\n- Copy the admin private key from the deployment output (starts with `0x`)\n- In MetaMask, go to Account → Import Account\n- Paste the private key to import the admin account\n\n#### 5. Connect MetaMask to Local Network\n\n- Switch to the \"Hardhat Local\" network in MetaMask\n- Ensure you're using the imported admin account\n\n#### 6. Start the Frontend Application\n\n```bash\ncd apps/dashboard\nyarn dev\n```\n\nThis starts the dashboard at `http://localhost:3000`\n\n#### 7. Connect MetaMask to the App\n\n- Open `http://localhost:3000` in your browser\n- Click \"Connect Wallet\" in the app\n- Approve the MetaMask connection request\n\n**🎉 You're now ready to develop locally!**\n\n### Production/Testnet Setup\n\nFor production or testnet development, you can skip steps 1-3 and use existing deployed contracts:\n\n```bash\n# Start only the frontend\ncd apps/dashboard\nyarn dev\n```\n\nThis will start:\n\n- Dashboard app at `http://localhost:3000`\n\n## 📋 Project Structure\n\n```\nweb3-fullstack/\n├── apps/\n│   ├── contracts/          # Solidity smart contracts\n│   │   ├── contracts/      # Smart contract source files\n│   │   ├── scripts/        # Deployment and setup scripts\n│   │   ├── test/           # Contract tests\n│   │   └── hardhat.config.js\n│   └── dashboard/          # Next.js web application\n│       ├── src/\n│       │   ├── app/        # Next.js app router pages\n│       │   ├── components/ # React components\n│       │   ├── lib/        # Utilities and configurations\n│       │   ├── services/   # API services\n│       │   └── utils/      # Helper functions\n│       └── scripts/        # Dashboard utility scripts\n├── packages/\n│   ├── ui/                 # Shared UI components\n│   ├── eslint-config/      # ESLint configurations\n│   └── typescript-config/  # TypeScript configurations\n└── README.md\n```\n\n## 🔧 Smart Contracts\n\n### Overview\n\nThe platform consists of two main smart contracts:\n\n- **`FinancialPlatform.sol`**: Main contract managing users, transactions, and approvals\n- **`MockToken.sol`**: ERC20 token for testing financial transactions\n\n### Features\n\n- **Role-based Access Control**: Regular users, Managers, and Admins\n- **Transaction Workflow**: Create → Request Approval → Process → Complete\n- **User Management**: Registration and role assignment\n- **Approval System**: Multi-level approval with reason tracking\n- **Event Logging**: Comprehensive event system for audit trails\n\n### Contract Functions\n\n#### User Management\n\n```solidity\nregisterUser(address walletAddress, string name, string email, UserRole role)\nupdateUserRole(address userAddress, UserRole newRole)\ngetUser(address userAddress)\n```\n\n#### Transaction Management\n\n```solidity\ncreateTransaction(address to, uint256 amount, string description)\nrequestApproval(uint256 transactionId, string reason)\ncompleteTransaction(uint256 transactionId)\ngetTransaction(uint256 transactionId)\n```\n\n#### Approval System\n\n```solidity\nprocessApproval(uint256 approvalId, bool approved, string reason)\ngetApproval(uint256 approvalId)\ngetPendingApprovals()\n```\n\n## 🛠️ Development Scripts\n\n### Contract Development\n\n```bash\n# Navigate to contracts directory\ncd apps/contracts\n\n# Compile contracts\nyarn compile\n\n# Run tests\nyarn test\n\n# Start local Hardhat node\nyarn dev\n\n# Deploy contracts locally\nyarn deploy:localhost\n\n# Deploy to Sepolia testnet\nyarn deploy:sepolia\n\n# Deploy to Holesky testnet\nyarn deploy:holesky\n```\n\n### Dashboard Development\n\n```bash\n# Navigate to dashboard directory\ncd apps/dashboard\n\n# Start development server\nyarn dev\n\n# Run tests\nyarn test\n\n# Build for production\nyarn build\n\n# Start production server\nyarn start\n```\n\n### Environment Configuration\n\nThe dashboard uses environment variables for contract configuration. To set up:\n\n1. **Place deployment JSON file** in `apps/dashboard/scripts/` directory\n2. **Run conversion script**:\n   ```bash\n   cd apps/dashboard\n   yarn convert-deployment\n   ```\n3. **Restart development server**\n\nThe script will:\n\n- Find `deployment-info*.json` files in the scripts directory\n- Convert them to environment variables in `.env.local`\n- Make contract addresses and ABIs available to the frontend\n\n### Available Scripts\n\n#### Contract Scripts (`apps/contracts/`)\n\n- `yarn compile` - Compile smart contracts\n- `yarn test` - Run contract tests\n- `yarn dev` - Start local Hardhat node\n- `yarn deploy:localhost` - Deploy to local network\n- `yarn deploy:sepolia` - Deploy to Sepolia testnet\n- `yarn deploy:holesky` - Deploy to Holesky testnet\n\n#### Dashboard Scripts (`apps/dashboard/`)\n\n- `yarn dev` - Start development server\n- `yarn build` - Build for production\n- `yarn start` - Start production server\n- `yarn test` - Run tests\n- `yarn test:watch` - Run tests in watch mode\n- `yarn test:coverage` - Run tests with coverage\n- `yarn convert-deployment` - Convert deployment JSON to environment variables\n\n## 🔐 Security Features\n\n### Smart Contract Security\n\n- **Access Control**: OpenZeppelin's AccessControl for role management\n- **Reentrancy Protection**: ReentrancyGuard to prevent reentrancy attacks\n- **Input Validation**: Comprehensive require statements and modifiers\n- **Event Logging**: All state changes are logged for audit trails\n\n### Frontend Security\n\n- **Environment Variables**: Contract addresses and ABIs stored in environment variables\n- **Runtime Parsing**: JSON parsed at runtime with error handling\n- **Type Safety**: Full TypeScript support with strict type checking\n- **Error Boundaries**: Comprehensive error handling throughout the app\n\n## 🌐 Network Configuration\n\n### Supported Networks\n\n- **Localhost**: Development and testing (Chain ID: 31337)\n- **Sepolia**: Ethereum testnet (Chain ID: 11155111)\n- **Holesky**: Ethereum testnet (Chain ID: 17000)\n\n### Environment Variables\n\nCreate a `.env` file in `apps/contracts/` with:\n\n```env\nPRIVATE_KEY=your_wallet_private_key\nSEPOLIA_RPC_URL=your_sepolia_rpc_endpoint\nHOLESKY_RPC_URL=your_holesky_rpc_endpoint\nETHERSCAN_API_KEY=your_etherscan_api_key\n```\n\n## 🧪 Testing\n\n### Contract Testing\n\n```bash\ncd apps/contracts\nyarn test\n```\n\nTests cover:\n\n- User registration and role assignment\n- Transaction creation and approval workflow\n- Access control validation\n- Error handling for invalid operations\n- Event emission verification\n\n### Frontend Testing\n\n```bash\ncd apps/dashboard\nyarn test\n```\n\nTests cover:\n\n- Component rendering\n- User interactions\n- API integrations\n- Error handling\n\n## 🚀 Deployment\n\n### Smart Contracts\n\n1. **Set environment variables** in `apps/contracts/.env`\n2. **Deploy to target network**:\n   ```bash\n   cd apps/contracts\n   yarn deploy:sepolia  # or deploy:holesky\n   ```\n3. **Verify contracts** on Etherscan (automatic with deployment)\n\n### Dashboard\n\n1. **Convert deployment info** to environment variables\n2. **Build the application**:\n   ```bash\n   cd apps/dashboard\n   yarn build\n   ```\n3. **Deploy to your hosting platform** (Vercel, Netlify, etc.)\n\n## 📚 API Reference\n\n### Contract Manager\n\nThe dashboard uses a `ContractManager` class to interact with smart contracts:\n\n```typescript\nimport { contractManager } from '@/api/contract-manager';\n\n// Get contract instances\nconst financialPlatform = contractManager.getFinancialPlatform();\nconst mockToken = contractManager.getMockToken();\n\n// Interact with contracts\nawait financialPlatform.createTransaction(to, amount, description);\n```\n\n### Environment Variables\n\nThe app uses this environment variable:\n\n- `NEXT_PUBLIC_DEPLOYMENT_INFO`: JSON string with contract addresses, ABIs, and network information\n\n## 🤝 Contributing\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Commit your changes**: `git commit -m 'Add amazing feature'`\n4. **Push to the branch**: `git push origin feature/amazing-feature`\n5. **Open a Pull Request**\n\n### Development Guidelines\n\n- Follow TypeScript best practices\n- Write comprehensive tests\n- Use conventional commit messages\n- Update documentation for new features\n\n## 🆘 Support\n\nIf you encounter any issues:\n\n1. Check the [Issues](https://github.com/ivanms1/web3-fullstack/issues) page\n2. Create a new issue with detailed information\n3. Include steps to reproduce the problem\n\n## 🔗 Useful Links\n\n- [Turborepo Documentation](https://turborepo.com/docs)\n- [Next.js Documentation](https://nextjs.org/docs)\n- [Hardhat Documentation](https://hardhat.org/docs)\n- [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts/)\n- [Ethers.js Documentation](https://docs.ethers.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivanms1%2Fweb3-fullstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivanms1%2Fweb3-fullstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivanms1%2Fweb3-fullstack/lists"}