{"id":49841897,"url":"https://github.com/EveULuvMe/singuhunt-contracts","last_synced_at":"2026-05-30T21:00:38.462Z","repository":{"id":346128649,"uuid":"1187696278","full_name":"EveULuvMe/singuhunt-contracts","owner":"EveULuvMe","description":"PVP game inside EVE frontier","archived":false,"fork":false,"pushed_at":"2026-04-22T07:11:45.000Z","size":173,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T08:30:04.817Z","etag":null,"topics":["evefrontir","pvp","sui"],"latest_commit_sha":null,"homepage":"https://eveuluv.me/","language":"Move","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EveULuvMe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2026-03-21T03:16:43.000Z","updated_at":"2026-04-22T07:11:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/EveULuvMe/singuhunt-contracts","commit_stats":null,"previous_names":["k66inthesky/singuhunt","eveuluvme/singuhunt"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/EveULuvMe/singuhunt-contracts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EveULuvMe%2Fsinguhunt-contracts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EveULuvMe%2Fsinguhunt-contracts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EveULuvMe%2Fsinguhunt-contracts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EveULuvMe%2Fsinguhunt-contracts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EveULuvMe","download_url":"https://codeload.github.com/EveULuvMe/singuhunt-contracts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EveULuvMe%2Fsinguhunt-contracts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33709269,"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-05-30T02:00:06.278Z","response_time":92,"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":["evefrontir","pvp","sui"],"created_at":"2026-05-14T07:01:36.526Z","updated_at":"2026-05-30T21:00:38.455Z","avatar_url":"https://github.com/EveULuvMe.png","language":"Move","funding_links":[],"categories":["Move"],"sub_categories":[],"readme":"# Singu Hunt Contracts\n\nSui Move contracts for the Singu Hunt game loop.\n\nThis repository contains the current on-chain gameplay layer for Singu Hunt, including registration, EVE-denominated entry fees, multi-mode hunt logic, shard collection and delivery, achievement minting, ticket verification, and bulletin-board support for the in-world SSU flow.\n\nNo production links are included in this README.\n\nJoin the Discord community at \u003chttps://discord.gg/5bGUfNngHw\u003e to report technical issues or share suggestions.\n\n## English\n\n### What This Package Does\n\n- opens and closes registration windows\n- sells `RegistrationPass` objects\n- supports an EVE-denominated registration path\n- runs daily hunt state and gate selection\n- tracks shard collection and delivery\n- supports solo race, team race, deep decrypt, large arena, and obstacle run modes\n- mints `AchievementNFT`\n- provides SSU bulletin-board support\n\n### System Architecture\n\nThree-tier composition: off-chain frontend + ticket signer; on-chain `singuhunt` package owning shared `GameState` and treasuries; downstream `singuvault-contracts` consumes the minted `AchievementNFT`.\n\n```mermaid\ngraph TB\n    subgraph \"Off-chain\"\n        App[singuhunt-app SPA]\n        Backend[Ticket Signer Service]\n    end\n    subgraph \"Sui Chain — singuhunt package\"\n        GameState[(GameState shared)]\n        ShardTreasury[(SinguShardTreasury)]\n        AchievementTreasury[(AchievementTreasury)]\n        Bulletin[(BulletinBoard)]\n        Reg[RegistrationPass]\n        Record[SinguShardRecord]\n        NFT[AchievementNFT]\n    end\n    subgraph \"Downstream\"\n        Vault[singuvault-contracts]\n    end\n\n    App --\u003e|buy_registration_pass / _eve| GameState\n    GameState --\u003e Reg\n    App --\u003e|activate_registration| GameState\n    App --\u003e|register_for_hunt| GameState\n    App --\u003e|collect_singu_shard| Record\n    ShardTreasury --\u003e Record\n    App --\u003e|deliver_singu_shard| GameState\n    Backend --\u003e|signs claim ticket| App\n    App --\u003e|claim_achievement w/ ticket| GameState\n    AchievementTreasury --\u003e NFT\n    NFT --\u003e|redeemable in| Vault\n    App --\u003e|create / visit| Bulletin\n```\n\n### Repository Layout\n\n`move-contracts/singuhunt/gate-and-ssu/sources/singuhunt.move`\nCore game state, registration, hunt lifecycle, shard collection, shard delivery, and mode-specific achievement claim logic.\n\n`move-contracts/singuhunt/gate-and-ssu/sources/achievement_token.move`\nAchievement treasury and token primitives.\n\n`move-contracts/singuhunt/gate-and-ssu/sources/singu_shard_token.move`\nShard treasury and token primitives used during live hunt sessions.\n\n`move-contracts/singuhunt/gate-and-ssu/sources/sig_verify.move`\nTicket-signature verification helpers.\n\n`move-contracts/singuhunt/gate-and-ssu/sources/bulletin_board.move`\nBulletin-board state used by the SSU-style in-world interaction surface.\n\n`move-contracts/singuhunt/gate-and-ssu/tests/singuhunt_tests.move`\nUnit tests covering solo race, team race, deep decrypt, large arena, and obstacle run claim paths.\n\n### Main Objects\n\n`GameState`\nShared state object storing epoch, active hunt window, configured gates, ticket signer, registration data, fee data, and cumulative counters.\n\n`RegistrationPass`\nTransferable pass bought during registration and later consumed by `activate_registration`.\n\n`SinguShardRecord`\nPer-player progress object representing shard state for the current epoch.\n\n`AchievementNFT`\nPermanent achievement object minted to successful players.\n\n`AdminCap`\nAdmin capability used to configure gates, signer, registration windows, and hunt control.\n\n### Supported Modes\n\nThe package currently defines five modes:\n\n- `1` solo race\n- `2` team race\n- `3` deep decrypt\n- `4` large arena\n- `5` obstacle run\n\nCurrent registration fee constants are all `1 EVE` in smallest units:\n\n- `REG_FEE_SOLO_RACE = 1_000_000_000`\n- `REG_FEE_TEAM_RACE = 1_000_000_000`\n- `REG_FEE_DEEP_DECRYPT = 1_000_000_000`\n- `REG_FEE_LARGE_ARENA = 1_000_000_000`\n- `REG_FEE_OBSTACLE_RUN = 1_000_000_000`\n\n### Main Entry Functions\n\nAdmin-side:\n\n- `set_start_gate`\n- `set_end_gate`\n- `set_pool_gate`\n- `set_shard_gate`\n- `set_ticket_signer`\n- `set_required_singu_count`\n- `open_registration`\n- `withdraw_registration_fees`\n- `finalize_team_registration`\n- `start_hunt_with_selection`\n- `start_hunt`\n- `expire_hunt`\n\nPlayer-side:\n\n- `buy_registration_pass`\n- `buy_registration_pass_eve\u003cT\u003e`\n- `activate_registration`\n- `register_for_hunt`\n- `register_for_hunt_with_character_id`\n- `collect_singu_shard`\n- `deliver_singu_shard`\n- `claim_achievement`\n- `claim_team_achievement`\n- `claim_decrypt_achievement`\n- `burn_expired_singu_shard`\n\nBulletin-board:\n\n- `create_bulletin`\n- `update_motd`\n- `visit_bulletin`\n\n### Contract Flow\n\n```text\nadmin opens registration\n  -\u003e player buys RegistrationPass\n  -\u003e player activates registration\n  -\u003e admin finalizes teams if mode requires it\n  -\u003e admin starts hunt\n  -\u003e players collect and deliver shards\n  -\u003e successful players claim AchievementNFT\n```\n\n```mermaid\nflowchart LR\n    A[open_registration] --\u003e B[buy_registration_pass or buy_registration_pass_eve]\n    B --\u003e C[activate_registration]\n    C --\u003e D[start_hunt]\n    D --\u003e E[collect_singu_shard]\n    E --\u003e F[deliver_singu_shard]\n    F --\u003e G[claim_achievement / claim_team_achievement / claim_decrypt_achievement]\n    G --\u003e H[AchievementNFT]\n```\n\n### Frontend / App Relationship\n\n- `singuhunt-app`\n  Player-facing frontend for registration, hunt participation, shard interaction, and claim flow.\n- `singuvault-contracts`\n  Later redemption destination for `AchievementNFT`.\n- `singuvault-app`\n  Player-facing frontend that redeems the achievement after it is earned here.\n\n```mermaid\nflowchart LR\n    HC[singuhunt-contracts] --\u003e|AchievementNFT| VC[singuvault-contracts]\n    HA[singuhunt-app] --\u003e|registration / hunt / claim| HC\n    VA[singuvault-app] --\u003e|redeem and vault UI| VC\n```\n\n### Current App-Side Config Surface\n\nThe current `singuhunt-app` expects env / config values for:\n\n- `VITE_GAME_STATE_ID`\n- `VITE_SINGUHUNT_PACKAGE_ID`\n- `VITE_SINGUHUNT_CALL_PACKAGE_ID`\n- `VITE_EVE_COIN_TYPE`\n- `VITE_SUI_RPC_URL`\n- `VITE_TICKET_API_URL`\n\nCommon object IDs expected by the frontend:\n\n- `SINGU_SHARD_TREASURY_ID`\n- `ACHIEVEMENT_TREASURY_ID`\n- shared `GAME_STATE_ID`\n\nIf the package or shared objects are republished, update the frontend env values before release.\n\n### Integration Notes\n\n- `Move.toml` depends on the local `singuvault` package.\n- `singuhunt.move` now imports `singuvault::eve::EVE`.\n- `buy_registration_pass_eve\u003cT\u003e` enforces the configured EVE coin type and forwards the fee to `REGISTRATION_FEE_RECEIVER`.\n- `buy_registration_pass` now also consumes `Coin\u003cEVE\u003e`.\n- The achievement image path is hardcoded in code and should stay aligned with the frontend asset path.\n\n### Build And Publish\n\nBuilding requires the `singuvault-contracts` repo cloned alongside this repo at the relative path `../../../../singuvault-contracts/move-contracts/singuvault` (as referenced in `Move.toml`).\n\n```bash\ncd move-contracts/singuhunt/gate-and-ssu\nsui move build\nsui client publish --gas-budget 200000000\n```\n\nCurrent `Move.toml` references:\n\n- Sui framework `testnet-v1.66.2`\n- local dependency `../../../../singuvault-contracts/move-contracts/singuvault`\n\n## 中文\n\n### 這個合約包現在負責什麼\n\n- 開啟與關閉報名窗口\n- 發售 `RegistrationPass`\n- 支援以 EVE 支付報名費\n- 管理每日 hunt 狀態與 gate 配置\n- 記錄 shard 收集與交付\n- 支援五種模式：Solo Race、Team Race、Deep Decrypt、Large Arena、Obstacle Run\n- 鑄造 `AchievementNFT`\n- 提供 SSU bulletin board 狀態\n\n### 主要物件\n\n`GameState`\n共享遊戲狀態，保存 epoch、hunt 時間、gate、ticket signer、報名狀態與費用資料。\n\n`RegistrationPass`\n玩家報名購買後拿到的通行物件，之後會被 `activate_registration` 消耗。\n\n`SinguShardRecord`\n玩家在當前 epoch 的 shard 進度物件。\n\n`AchievementNFT`\n成功通關後鑄造的永久成就物件。\n\n`AdminCap`\n管理員能力物件，用於設定 gate、signer、報名與 hunt 控制。\n\n### 與其他倉庫的關係\n\n- `singuhunt-app`\n  直接呼叫本倉庫的 entry functions，提供玩家報名、收集、交付與 claim 體驗\n- `singuvault-contracts`\n  之後會接收本倉庫鑄造出的 `AchievementNFT`\n- `singuvault-app`\n  玩家拿到 Achievement 後，去這個前端選擇兌換或質押路徑\n\n### 前端部署時要對齊的設定\n\n重新發版或重建 shared object 時，至少要同步更新 `singuhunt-app`：\n\n- `VITE_GAME_STATE_ID`\n- `VITE_SINGUHUNT_PACKAGE_ID`\n- `VITE_SINGUHUNT_CALL_PACKAGE_ID`\n- `VITE_EVE_COIN_TYPE`\n- `VITE_TICKET_API_URL`\n- `SINGU_SHARD_TREASURY_ID`\n- `ACHIEVEMENT_TREASURY_ID`\n\n### 部署\n\n編譯前需要在相對路徑 `../../../../singuvault-contracts/move-contracts/singuvault` 有 `singuvault-contracts` 倉庫（`Move.toml` 的 local dependency）。\n\n```bash\ncd move-contracts/singuhunt/gate-and-ssu\nsui move build\nsui client publish --gas-budget 200000000\n```\n\n## License\n\nCopyright (c) Eve U Luv Me. All rights reserved.\n\nThis repository is proprietary and is not licensed under MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEveULuvMe%2Fsinguhunt-contracts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEveULuvMe%2Fsinguhunt-contracts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEveULuvMe%2Fsinguhunt-contracts/lists"}