{"id":32372131,"url":"https://github.com/themetalfleece/eldritchain","last_synced_at":"2026-07-11T17:31:34.218Z","repository":{"id":318746711,"uuid":"1075709962","full_name":"themetalfleece/eldritchain","owner":"themetalfleece","description":"dApp game where you can summon a creature daily. Beware, you might summon an Eldritch horror!","archived":false,"fork":false,"pushed_at":"2026-04-27T06:34:59.000Z","size":703,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T08:25:12.032Z","etag":null,"topics":["blockchain","collection","creature","dapp","eldritch","summon"],"latest_commit_sha":null,"homepage":"https://eldritchain.xyz/","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/themetalfleece.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-13T22:05:36.000Z","updated_at":"2026-04-27T06:35:05.000Z","dependencies_parsed_at":"2025-10-15T01:32:45.422Z","dependency_job_id":null,"html_url":"https://github.com/themetalfleece/eldritchain","commit_stats":null,"previous_names":["themetalfleece/eldritchain"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/themetalfleece/eldritchain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themetalfleece%2Feldritchain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themetalfleece%2Feldritchain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themetalfleece%2Feldritchain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themetalfleece%2Feldritchain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/themetalfleece","download_url":"https://codeload.github.com/themetalfleece/eldritchain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themetalfleece%2Feldritchain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35370428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"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":["blockchain","collection","creature","dapp","eldritch","summon"],"created_at":"2025-10-24T21:50:57.792Z","updated_at":"2026-07-11T17:31:34.201Z","avatar_url":"https://github.com/themetalfleece.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Eldritchain\n\nA decentralized daily creature summoning dApp built on Ethereum. Summon a random creature once per day and build your collection of common animals, rare predators, epic Lovecraftian monsters, and legendary eldritch deities.\n\n## 📚 Documentation\n\n- **[Quick Start](docs/QUICKSTART.md)** - Get up and running in 10 minutes\n- **[Network Configuration](docs/NETWORK_CONFIGURATION.md)** - Switch between chains (Mainnet, Polygon, etc.)\n- **[Polygon Migration](docs/POLYGON_MIGRATION.md)** - Understanding MATIC → POL migration\n- **[UTC Day System](docs/UTC_DAY_SYSTEM.md)** - Once per day resets at midnight UTC (not 24h cooldown!)\n- **[Adding Creatures](docs/ADDING_CREATURES.md)** - Auto-sync script reads your data file\n- **[ID System](docs/ID_SYSTEM.md)** - Proportional namespaces explained\n- **[Gacha Distribution](docs/GACHA_DISTRIBUTION.md)** - Why 97 creatures is optimal\n- **[Testing Guide](docs/TESTING.md)** - How to test your deployment\n\n## Project Overview\n\nEldritchain is a blockchain-based game where users can:\n\n- Summon one creature per UTC day (resets at midnight UTC, not 24h cooldown)\n- Collect 97 unique creatures across 4 rarity tiers\n- Level up creatures by summoning them multiple times\n- View their entire collection on-chain\n\n### Rarity Distribution (Optimized for Gacha)\n\n- **Common (70%)**: 60 creatures - IDs 0-59 (namespace: 0-999, 1000 slots)\n- **Rare (25%)**: 20 creatures - IDs 1000-1019 (namespace: 1000-1499, 500 slots)\n- **Epic (4.5%)**: 12 creatures - IDs 1500-1511 (namespace: 1500-1599, 100 slots)\n- **Deity (0.5%)**: 5 creatures - IDs 1600-1604 (namespace: 1600-1649, 50 slots)\n\n**Total: 97 creatures** with proportional namespace sizes! Auto-sync script reads your data file and updates the contract automatically. See [ID System](docs/ID_SYSTEM.md) and [Adding Creatures](docs/ADDING_CREATURES.md).\n\n## Architecture\n\nThis is a monorepo containing two main applications:\n\n```\neldritchain/\n├── apps/\n│   ├── contracts/   # Solidity smart contracts (Hardhat)\n│   ├── web/         # Next.js frontend (React + Wagmi)\n│   └── indexer/     # Backend API \u0026 event indexer (Node.js + MongoDB)\n├── packages/\n│   └── common/      # Shared constants, types, and utilities\n├── package.json     # Root workspace configuration\n└── README.md        # This file\n```\n\n### Technology Stack\n\n**Smart Contracts:**\n\n- Solidity 0.8.24\n- Hardhat for development and deployment\n- Upgradeable (UUPS proxy pattern)\n- Network-agnostic (Sepolia, Mainnet, Polygon, Arbitrum, Base, etc.)\n\n**Frontend:**\n\n- Next.js 15 with App Router\n- TypeScript\n- Tailwind CSS for styling\n- Wagmi v2 + Viem for blockchain interaction\n- RainbowKit for wallet connection\n\n**Backend (Indexer):**\n\n- Node.js + TypeScript\n- Express REST API\n- MongoDB for event storage\n- Viem for blockchain event listening\n- Docker Compose for local MongoDB\n\n**Shared Package:**\n\n- `@eldritchain/common` - Centralized constants, types, and utilities\n- Single source of truth for creature ranges and rarity logic\n- Shared across all apps\n\n**Code Quality:**\n\n- ESLint + Prettier for consistent formatting\n- Enforced curly braces and best practices\n- GitHub Actions CI for automated testing\n- Runs on every push: lint, format check, contract tests, and build\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 22.14.0 (install via nvm, see below)\n- Yarn package manager\n- A wallet with Sepolia testnet ETH\n- WalletConnect Project ID (get from https://cloud.walletconnect.com/)\n\n**Node.js Setup (with nvm):**\n\n```bash\n# Install Node.js version specified in .nvmrc\nnvm install\nnvm use\n```\n\nThe project includes `.nvmrc` files in the root and both apps to ensure consistent Node.js versions across development and CI.\n\n### Installation\n\n1. Clone the repository:\n\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd eldritchain\n```\n\n2. Copy `.env.example` files and configure your environment:\n\n```bash\n# Contracts environment\ncp apps/contracts/.env.example apps/contracts/.env\n# Edit apps/contracts/.env with your private key and RPC URLs\n\n# Web app environment (Next.js requires .env.local, not .env)\ncp apps/web/.env.example apps/web/.env.local\n# Edit apps/web/.env.local with your contract address and RPC URL\n```\n\n3. Install dependencies:\n\n```bash\nyarn install\n```\n\n## Quick Commands\n\nThe monorepo uses workspace shortcuts for easy command execution:\n\n```bash\n# Web app\nyarn web dev           # Start dev server\nyarn web build         # Build for production\nyarn web lint          # Lint code\n\n# Contracts\nyarn contracts compile      # Compile Solidity\nyarn contracts test         # Run tests\nyarn contracts deploy       # Deploy to network\n\n# Root (affects all workspaces)\nyarn lint              # Lint all packages\nyarn lint:fix          # Auto-fix linting issues\nyarn format            # Format all code\n```\n\n## Detailed Setup\n\n3. Set up the contracts:\n\n```bash\ncd apps/contracts\nyarn install\ncp .env.example .env\n# Edit .env with your private key and RPC URL\n```\n\n4. Set up the web app:\n\n```bash\ncd ../web\nyarn install\ncp .env.example .env\n# Edit .env with contract address and WalletConnect ID\n```\n\n## Development\n\n### Deploy Smart Contract\n\nSee detailed instructions in [apps/contracts/README.md](apps/contracts/README.md)\n\n```bash\n# From root directory\nyarn contracts compile\nyarn contracts test\nyarn contracts deploy\n```\n\n### Run Frontend\n\nSee detailed instructions in [apps/web/README.md](apps/web/README.md)\n\n```bash\n# From root directory\nyarn web dev\n```\n\nVisit http://localhost:3000\n\n## Smart Contract Features\n\n### Daily Summon System\n\n**Once per UTC day** (not 24-hour cooldown):\n\n- Summon at 11:59 PM → Can summon again at 12:01 AM! ✅\n- Based on calendar days, not time since last summon\n- Fair for all timezones using UTC as reference\n\n### Anti-Spoofing Measures\n\nThe contract uses multiple sources of randomness to prevent manipulation:\n\n- `block.timestamp` - Current block time\n- `block.prevrandao` - Random value from consensus\n- `msg.sender` - User's address\n- `blockhash(block.number - 1)` - Previous block hash\n\nThis makes it computationally infeasible for users to manipulate their summon results.\n\n### On-Chain Data\n\nThe contract stores:\n\n- User creature collection (mapping of creature ID to level)\n- Last summon timestamp per user\n- Rarity tier ranges as constants\n\nThe contract does **NOT** store:\n\n- Creature names, descriptions, or metadata (stored in frontend for gas efficiency)\n\n## Project Structure\n\n### `/apps/contracts`\n\n- `contracts/Eldritchain.sol` - Main smart contract\n- `scripts/deploy.ts` - Deployment script\n- `test/Eldritchain.test.ts` - Contract tests\n- `hardhat.config.ts` - Hardhat configuration\n\n### `/apps/web`\n\n- `src/app/` - Next.js pages\n- `src/components/` - React components\n- `src/config/` - Contract ABI and Wagmi configuration\n- `src/data/` - Creature metadata (141 creatures)\n\n## Contributing\n\nThis is a personal project, but feel free to fork and modify it for your own use!\n\n## License\n\nMIT License - feel free to use this code for your own projects.\n\n## Support\n\nIf you encounter issues:\n\n1. Check that you have Sepolia ETH in your wallet\n2. Verify your `.env` files are configured correctly\n3. Ensure you're connected to Sepolia network in your wallet\n4. Check that 24 hours have passed since your last summon\n\n## Acknowledgments\n\n- Lovecraftian creature concepts inspired by H.P. Lovecraft's works\n- Built with modern Web3 tooling (Wagmi, RainbowKit, Viem)\n- Deployed on Ethereum Sepolia testnet\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthemetalfleece%2Feldritchain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthemetalfleece%2Feldritchain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthemetalfleece%2Feldritchain/lists"}