StarQuest

Problem Statement

StarQuest is an on-chain GameFi backend built for Hedera EVM that implements a complete, auditable infrastructure for a location-based treasure-hunt experience:focusing on the trustworthy, low-fee economic and audit plane (staking, rewards, tokens, storage, and consensus anchoring) At the center is the StarQuest Core game logic (an EVM contract) which models stars, stakes, challenge lifecycle and payouts: players (via the mobile client) connect a wallet, inspect a geo-anchored star, and create an on-chain Staked transaction that records the stake, star id and player address; the Core emits lifecycle events such as Staked, ChallengeCompleted and RewardPaid that drive downstream actions. Financial settlement and native token economics are handled by the HTS façade contract: this contract implements convenience functions that call Hedera Token Service semantics from the EVM layer (create/mint/burn/associate tokens), enabling the system to mint fungible SQ tokens or SQNFTs and execute low-fee native payouts while preserving EVM-style calls and access control; its events (TokenCreated, TokenMinted, TokenBurned) let frontends and indexers reconcile balances. Price and verification primitives are exposed by the Oracle contract which stores asset identifiers, price values and location attestations and manages an authorizedOracles set—this contract is designed so a backend oracle or third-party oracle network can push signed price updates (PriceUpdated) and location verifications (LocationVerified) that the Core contract can trust when computing HBAR-denominated payouts or validating proximity-based triggers. To provide tamper-proof audit trails and dispute resolution, the Consensus contract implements HCS anchoring patterns: off-chain services relay Hedera Consensus Service message IDs and confirmations into the EVM via submitGameEvent / confirmHCSMessage entrypoints so every critical game event (stakes, completions, disputes, leaderboard updates) can be cryptographically anchored to Hedera Consensus and later audited via HCSMessageConfirmed logs. For long-term storage of player proofs and metadata, the Filecoin Storage contract records IPFS CIDs, storage requests and payments on-chain (events like StorageRequested, StorageCompleted), while an off-chain storage gateway performs pinning and Filecoin deal orchestration; the contract therefore makes CIDs first-class on-chain references with payment and access control, but delegates heavy storage work off-chain. Architecturally the repo and deployment reflect these responsibilities: contracts are authored in Solidity 0.8.19, compiled with Hardhat/typechain/ethers v6, unit-tested, deployed to Hedera Testnet and verified on Hashscan with ABIs and build metadata committed to the public GitHub repo (the deploy script writes hedera-deployment.json with addresses/timestamp for reproducibility). Runtime parameters—minimum and maximum stake (example 0.01–10 HBAR), rarity multipliers (Common 1.5x → Legendary 5x), house fee, and per-star proximity radii (configurable 1.5 m → 300 m)—are configurable on-chain or by admin. Security patterns include role-based access control (Ownable/admin guards), event-driven state changes for off-chain relayers to follow, and standard reentrancy and sanity checks in token flows; the Consensus contract’s multi-oracle/dispute design lets the protocol aggregate attestations before finalizing payouts. In practice the live demo walks through compilHedera-native economic & audit backbone that satisfies the competition requirements (deploy to Hedera EVM, verify on Hashscanct, off-chain relayer confirms proximity and posts an HCS message and/or an oracle price update, the Consensus contract records/anchors the HCS message ID, and the HTS façade mints/transfers the token reward, emitting RewardPaid and TokenMinted events that complete the economic cycle.The contracts instead include explicit hooks such as submitAIDecision and verifyLocation so you can plug in on-device ML or an AI oracle later), which allowed the team to concentrate on delivering a production-grade, Hedera-native economic & audit backbone that satisfies the competition requirements (deploy to Hedera EVM, verify on Hashscan, public source, demo video) auditable integrations for future releases.

Solution

ArchitectureMobile app (React Native + Expo) — wallet connect, map display, and user interactions.Backend (Node.js + TypeScript + Express + MongoDB) — relayers, event processors, and services that call contracts and coordinate on-chain/off-chain workflows.Smart contracts (Solidity 0.8.19, Hardhat, TypeChain, ethers) — the on-chain core that enforces game rules, token lifecycle, oracles, consensus anchoring and storage references.Integration SDK (JavaScript) — unified client library for contract calls, event listening and admin/bulk ops.Off-chain storage: IPFS CIDs recorded on-chain; Filecoin/back-end gateway handles pinning and deal orchestration.Key partner technologies & benefitsHedera Hashgraph (EVM + HTS + HCS) — ultra-low fees, high TPS and fast finality; enabled micro-stakes, low-cost payouts, and immutable consensus anchoring for audits.Hedera Token Service (HTS) — native token & NFT issuance (used through an EVM façade) so tokens are cheap and fast to mint/transfer.WalletConnect / MetaMask — mobile wallet integrations for secure, user-friendly signing.OpenZeppelin — secure, standards-tested contract primitives.IPFS / Filecoin — durable off-chain storage with on-chain CID references for proofs and metadata. These partners gave StarQuest low operational cost, fast UX for micro-transactions, and a straightforward path to native token economics.How pieces are stitched togetherUser (mobile) initiates a stake → signs a transaction to StarQuest Core.Core contract records the stake and emits lifecycle events (Staked, ChallengeCompleted, RewardPaid).Backend relayers observe events, confirm off-chain conditions, and relay HCS messages that are anchored via the Consensus contract.When payouts are due, the HTS façade mints/transfers native tokens (SQ / SQNFT) and emits token lifecycle events for frontends/indexers.Proofs/metadata CIDs are written to the Filecoin Storage contract; the backend performs pinning/filing deals off-chain.The Oracle contract holds price and verification primitives (authorized oracle set + price/location values) to let on-chain logic compute accurate HBAR-denominated payouts.Notable hacks & engineering choices (what’s worth calling out)HTS façade (EVM → HTS): implemented a contract layer that maps EVM calls to Hedera native token operations so the project benefits from native token efficiency while keeping EVM access control and tooling.HCS anchoring pattern: relayers post Hedera Consensus message IDs into the Consensus contract so game events are cryptographically anchored for audits and dispute resolution.Gas / data optimizations:Fixed-point coordinates (store lat/long as int scaled by 1e6) for compact, deterministic location math.Struct packing and gas-aware types to reduce calldata/storage costs.Batch operations (e.g., batchUpdatePrices) to amortize gas across many updates.Reproducible deploys: Hardhat deploy scripts write hedera-deployment.json (addresses, chain id, deployer, timestamp) to make verification and reproduction straightforward.Security primitives: OpenZeppelin patterns, Ownable/admin guards, nonReentrant modifiers, and multi-oracle aggregation for dispute resilience.Contracts (core on-chain components){StarQuest Core} — game logic: stars, stakes, lifecycle, reward triggers.{StarQuest HTS} — HTS façade: create/mint/burn/associate tokens (SQ / SQNFT).{StarQuest Oracle} — on-chain price/location storage & authorized oracle management.{StarQuest Consensus} — HCS anchoring, event confirmation, leaderboard/dispute aggregation.{StarQuest Filecoin Storage} — CID registry, storage requests, payment accounting for proofs.