|
| 1 | +# LunoKit |
| 2 | + |
| 3 | +- **Team Name:** LunoLab |
| 4 | +- **Payment Details:** |
| 5 | + - **DOT**: 14pGVuuBxbN9dVNGh2a6dNqAEP7f48z7ks5vH9WNXKakUm7Z |
| 6 | + - **Payment**: 14pGVuuBxbN9dVNGh2a6dNqAEP7f48z7ks5vH9WNXKakUm7Z (USDC). |
| 7 | +- **[Level](https://grants.web3.foundation/docs/Introduction/levels):** 2 |
| 8 | + |
| 9 | +## Project Overview :page_facing_up: |
| 10 | + |
| 11 | +### Overview |
| 12 | +LunoKit is the core open-source product developed by the Lunolab team, aiming to build a customizable UI-themed, developer-friendly Web3 account connection infrastructure for the Polkadot ecosystem. It unifies wallet connection state management, account abstraction, chain switching, and session recovery, while also providing a rich set of UI components and multi-chain account support, greatly reducing the integration threshold for DApps built on Polkadot SDK chains. |
| 13 | +As a frontend development library based on React + TypeScript, LunoKit also provides over 20 Hooks, including account state management, chain switching, connection control, and on-chain data subscription, with support for data caching. Developers can focus on core business logic while LunoKit handles the account module. |
| 14 | + |
| 15 | +### Project Details |
| 16 | + |
| 17 | +#### 1. User Interface Component Design |
| 18 | +LunoKit will provide a set of React UI components for account connection, covering common functionalities such as connect button, wallet selection modal, account details modal, network switcher, and asset display panel. All components are responsive, adapting to both mobile and desktop, and support custom themes. |
| 19 | + |
| 20 | + |
| 21 | +#### 2. Architecture Design and Core Modules |
| 22 | + |
| 23 | +LunoKit adopts a clear three-layer modular architecture, handling connection logic, React integration, and UI presentation respectively: |
| 24 | + |
| 25 | +#### `@luno-kit/core` |
| 26 | +Encapsulates wallet connectors, chain configuration, and account management underlying logic, providing unified connection states and signer interfaces. |
| 27 | + |
| 28 | +#### `@luno-kit/react` |
| 29 | +The integration layer built with React, providing over 20 composable Hooks for managing connection states, chain switching, and on-chain data subscriptions. |
| 30 | + |
| 31 | +Common Hooks examples: |
| 32 | + |
| 33 | +- `useAccount()` / `useAccounts()` |
| 34 | +- `useConnect()` / `useDisconnect()` |
| 35 | +- `useChains()` / `useSwitchChain()` |
| 36 | +- `useSubscription()` / `useBalance()` / `useBlockNumber()` |
| 37 | +- `useSendTransaction()` / `useSignMessage()` / `useSigner()` |
| 38 | + |
| 39 | +#### `@luno-kit/ui` |
| 40 | +Provides plug-and-play components such as connect buttons, account panels, and network switchers, supporting style and theme customization. |
| 41 | + |
| 42 | +### Tech Stack Overview |
| 43 | +| Technology | Purpose | Module | |
| 44 | +|--------------------------|--------------------------------------------|----------------------------| |
| 45 | +| TypeScript | Type safety, improved development efficiency | All modules | |
| 46 | +| React 18 | Building UI and lifecycle logic | @luno-kit/react, @luno-kit/ui | |
| 47 | +| Zustand | Centralized state management (connection state, accounts, chain) | @luno-kit/react | |
| 48 | +| TanStack React Query | On-chain data subscription, cache updates | @luno-kit/react, @luno-kit/ui | |
| 49 | +| Dedot | Lightweight and modern Polkadot API alternative, better performance and smaller bundle size | @luno-kit/core, @luno-kit/react | |
| 50 | +| Tailwind CSS 4.x | Responsive component styling | @luno-kit/ui | |
| 51 | +| Radix UI | Accessible interactive component foundation | @luno-kit/ui | |
| 52 | + |
| 53 | +### Ecosystem Fit |
| 54 | + |
| 55 | +#### Target Audience of LunoKit: |
| 56 | +- **Parachain development teams**: Need to quickly integrate account connection modules into chain websites, governance platforms, or marketing pages. |
| 57 | +- **DApp development teams**: Teams building DeFi, NFT, DAO, GameFi, etc., often facing challenges of multi-wallet compatibility and connection state management. |
| 58 | +- **UI developers**: Seeking accessible, theme-customizable, componentized wallet connection UIs. |
| 59 | +- **Polkadot hackathon participants / startups**: Strong demand for "out-of-the-box" components to achieve high-quality connection experiences within limited time. |
| 60 | + |
| 61 | +#### What real needs does LunoKit address? |
| 62 | + |
| 63 | +In Polkadot/Substrate frontend development, developers have long faced issues such as inconsistent wallet access logic, complex state management, and lack of standardized UI. LunoKit systematically addresses the following key needs: |
| 64 | + |
| 65 | +- **Unified multi-wallet connection** |
| 66 | + Supports major injected wallets such as polkadot.js, Talisman, SubWallet, and NovaWallet. Provides a unified connector abstraction and type system to avoid high costs and errors caused by wallet interface differences. |
| 67 | + |
| 68 | +- **Standardized account & connection state management** |
| 69 | + Encapsulates connection state, current account, wallet source, chain info, and authorization state into a unified state model. Combined with React Hooks, provides highly composable integration and avoids repetitive logic in DApps. |
| 70 | + |
| 71 | +- **Multi-chain adaptability** |
| 72 | + Supports custom chain configuration and inter-chain switching, compatible with multi-parachain scenarios, suitable for multi-chain deployment applications. |
| 73 | + |
| 74 | +- **Plug-and-play connection UI components** |
| 75 | + Provides customizable connect buttons, account panels, network switchers, and asset lists. Fully a11y compliant, improves UI consistency and efficiency, reduces repetitive implementation. Components are responsive, mobile-friendly, and support Deeplink-based flows for wallet apps like SubWallet. |
| 76 | + |
| 77 | +- **On-chain data subscription & caching** |
| 78 | + Integrates Dedot and TanStack Query, encapsulates derive/storage query logic, supports auto-caching, state updates, and error recovery for efficiency and stability. |
| 79 | + |
| 80 | +- **Modern development process & framework support** |
| 81 | + Offers integration templates for CRA, Vite, Next.js, combined with TypeScript-first experience, Hooks system, and modular architecture. |
| 82 | + |
| 83 | +- **Custom UI system, decoupling components & logic** |
| 84 | + Core logic is provided as Hooks, enabling developers to skip default UI components and fully customize connect buttons, modals, etc., for diverse product styles and UX designs. |
| 85 | + |
| 86 | +- **PolkaVM Support** |
| 87 | + After completing Substrate support, LunoKit will support PolkaVM, enabling simultaneous connections to Substrate and EVM accounts, boosting efficiency for Solidity DApp developers on PolkaHub chains. |
| 88 | + |
| 89 | +#### Similar attempts in Substrate/Polkadot/Kusama ecosystem: |
| 90 | + |
| 91 | +- **SubConnect**: It has not been updated for nearly a year, with multiple issues left unanswered by developers and the project in a stagnant state ([reference link](https://github.com/Koniverse/SubConnect-v2/issues)). We tested and found that some of its functions are no longer usable. In addition, it is built on top of web3-onboard, with the core library heavily dependent on web3-onboard, which limits its long-term maintainability. |
| 92 | +- **Talisman Connect**: Officially deprecated ([issue](https://github.com/TalismanSociety/talisman-connect/issues/56)) |
| 93 | +- **Dot-Connect**: The functionality is relatively limited, only supporting basic wallet connection features and lacking a complete account module. The range of components is limited, and the UI and user experience quality are relatively weak. For development teams. |
| 94 | + |
| 95 | + |
| 96 | +#### Key Advantages of LunoKit: |
| 97 | + |
| 98 | +- TypeScript-first type system, clear interface specifications. |
| 99 | +- React Hooks-based modular encapsulation for state, accounts, chain switching, and subscriptions. |
| 100 | +- Decoupled state management and connection logic—developers can skip official UI and still use Hooks to build custom UIs. |
| 101 | +- Built-in customizable, responsive UI components (buttons, modals, switchers) with a11y compliance. |
| 102 | +- Complete examples & docs to reduce learning curve. |
| 103 | +- The core library is fully self-developed, does not rely on external repositories, and ensures controllable long-term maintenance and strong ecosystem adaptability. |
| 104 | + |
| 105 | + |
| 106 | +In the broader Web3 ecosystem, comparable tools include: |
| 107 | + |
| 108 | +- **wagmi (Ethereum)**: React Hooks for wallet connection and state. |
| 109 | +- **RainbowKit (Ethereum)**: Customizable wallet connection UI, designed to pair with wagmi. |
| 110 | + |
| 111 | +These are standards in Ethereum, but Polkadot lacks equivalents. LunoKit integrates both functionalities to fill this gap. |
| 112 | + |
| 113 | +## Team :busts_in_silhouette: |
| 114 | +### Team members |
| 115 | + |
| 116 | +- Leader: Cris Sun |
| 117 | +- Member: Brain (WBH) |
| 118 | + |
| 119 | +### Contact |
| 120 | + |
| 121 | +- **Contact Name:** Cris Sun |
| 122 | +- **Contact Email: ** [email protected] |
| 123 | +- **Website:** https://www.lunolab.xyz/ |
| 124 | + |
| 125 | +### Legal Structure |
| 126 | + |
| 127 | +- **Registered Address:** - |
| 128 | +- **Registered Legal Entity:** - |
| 129 | + |
| 130 | +### Team's experience |
| 131 | + |
| 132 | +**Lunolab** is composed of two core members with extensive blockchain development backgrounds. Since joining the **ChainX team** in 2020, they have been active in the Web3 field, participating in the incubation and development of multiple public chains and application projects. Cris has over 5 years of Web3 product experience, focusing on cross-chain protocol design and user experience optimization. He led the product design of ChainX, worked as a product manager responsible for OmniBTC’s frontend product design and project management, and from 2023–2025 served as the product lead of BEVM/GEB, overseeing chain-level functionality design and developer tool planning. Brain is a senior blockchain frontend developer. He joined the ChainX frontend team in 2020, began leading the frontend system development of OmniBTC in 2022 (including OmniSwap and OmniLending), and from 2023–2025 was fully responsible for the frontend architecture of BEVM/GEB, covering explorer, wallet, and developer tools, accumulating deep experience in blockchain frontend development. |
| 133 | + |
| 134 | +- **2020 – ChainX Team** |
| 135 | + |
| 136 | +- **June 2022 – OmniBTC (incubated within ChainX, now closed, social media [X](https://x.com/OmniBTC))** |
| 137 | + OmniBTC was a cross-chain DeFi platform that included two core products: |
| 138 | + - **OmniSwap**: A cross-chain trading aggregator supporting **40+ public chains** and **20+ cross-chain bridges**, with a cumulative trading volume exceeding **$2 billion**. |
| 139 | + - **OmniLending**: A cross-chain lending platform with peak TVL of over **$10 million**. |
| 140 | + |
| 141 | +- **June 2023 – June 2025, BEVM (incubated within ChainX, later renamed [GEB](https://www.geb.network/))** |
| 142 | + BEVM was a public chain developed with the Substrate technology stack, aiming to be a Bitcoin Layer 2 compatible with EVM smart contracts, with over **990,000 on-chain addresses**. |
| 143 | + |
| 144 | +### Team Code Repos |
| 145 | + |
| 146 | +- https://github.com/Luno-lab/LunoKit |
| 147 | + |
| 148 | +- https://github.com/wbh1328551759 (many non-open-sourced repos for GEB, contribution proof: [screenshot1](https://github.com/user-attachments/assets/de190fa2-3cff-486f-bcf0-4042cb8f1945), [screenshot2](https://github.com/user-attachments/assets/e8ef35ba-5a30-4345-a870-6b7f0989d47c)) |
| 149 | + |
| 150 | +- https://github.com/Gintma (Cris also has a certain development background and will be responsible for part of the UI-related code implementation) |
| 151 | + |
| 152 | +## Development Status :open_book: |
| 153 | + |
| 154 | +LunoKit has completed its initial version and has officially released a usable version. |
| 155 | + |
| 156 | +- **Demo Site** |
| 157 | + https://demo.lunolab.xyz |
| 158 | + |
| 159 | +- **GitHub Repo** |
| 160 | + https://github.com/Luno-lab/LunoKit |
| 161 | + |
| 162 | +- **Developer Docs** |
| 163 | + https://docs.lunolab.xyz/ |
| 164 | + |
| 165 | + |
| 166 | +## Development Roadmap :nut_and_bolt: |
| 167 | +### Overview |
| 168 | + |
| 169 | +- **Total Estimated Duration:** 3 months |
| 170 | +- **Full-Time Equivalent (FTE):** 2 |
| 171 | +- **Total Costs:** 30,000 USD |
| 172 | +- **DOT %:** 50% |
| 173 | + |
| 174 | +### Milestone 1 |
| 175 | + |
| 176 | +- **Estimated duration:** 1.5 months |
| 177 | +- **FTE:** 2 |
| 178 | +- **Costs:** 15,000 USD |
| 179 | + |
| 180 | +| No. | Deliverable | Specification | |
| 181 | +|------|-------------|---------------| |
| 182 | +| 0a. | License | MIT | |
| 183 | +| 0b. | Documentation | Provide a complete online documentation site, including installation guide, quick start, API reference, and integration examples. The documentation should cover core concepts, connector usage, and configuration options. | |
| 184 | +| 0c. | Tests & Test Guide | Core functionality is ensured through Vitest unit tests; covering connectors, utility functions, and configuration system. | |
| 185 | +| 0d. | Build System | Complete monorepo build; TypeScript compiled using tsup, supporting both ESM and CJS outputs. | |
| 186 | +| 0e. | Package Management | Use pnpm workspace and Changesets for version management and package publishing, supporting automated NPM publishing. | |
| 187 | +| 1. | Core Module: `@luno-kit/core` | Implement core connector abstraction (`BaseConnector`), configuration system (`createConfig`), chain definitions (`Chain` type), and storage system; support custom API options and type definitions. | |
| 188 | +| 2. | Wallet Connectors Collection | Implement 6 connectors: Polkadot{.js} Extension, SubWallet, Talisman, Polkagate, Nova Wallet, WalletConnect. Each connector supports account discovery, connection management, and signing. | |
| 189 | +| 3. | Chain Configuration System | Pre-configure 4 chains: Polkadot, Kusama, Westend, Paseo, including RPC endpoints, SS58, token info, and icons; support custom Substrate chain configurations. | |
| 190 | +| 4. | Utility Functions Library | Implement essential utility functions such as address format conversion, SS58 encoding/decoding, balance formatting, and device detection. | |
| 191 | +| 5. | Type System | Provide full TS types (`Account`, `Chain`, `Config`, `Connector`, `Signer`, etc.) to ensure type safety. | |
| 192 | +| 6. | UI Components: `@luno-kit/ui` | Implement 10 complete UI components: ConnectButton, ConnectModal, AccountDetailsModal, etc. | |
| 193 | +| 7. | Demo Website | Provide a fully functional demo website. | |
| 194 | + |
| 195 | + |
| 196 | +--- |
| 197 | + |
| 198 | +### Milestone 2 |
| 199 | +- **Estimated Duration:** 1.5 months |
| 200 | +- **FTE:** 2 |
| 201 | +- **Costs:** 15,000 USD |
| 202 | + |
| 203 | +| No. | Deliverable | Specification | |
| 204 | +|------|-------------|---------------| |
| 205 | +| 0a. | License | MIT | |
| 206 | +| 0b. | Documentation | Documentation expansion, including React Hooks API reference, UI component documentation, theme customization guide, and advanced usage tutorials. | |
| 207 | +| 0c. | Tests & Test Guide | Provide comprehensive tests for React components and Hooks: components tested with React Testing Library, Hooks tested with Vitest; cover all core functionalities. | |
| 208 | +| 0d. | Example Applications | Provide **4** complete examples: `with-vite` (Vite integration), `with-nextjs-app` (Next.js App Router), `with-nextjs-pages` (Next.js Pages Router), `with-cra` (Create React App). | |
| 209 | +| 0e. | CSS Styling System | Complete styling system based on Tailwind CSS, providing `@luno-kit/ui/styles.css` and CSS variable support. | |
| 210 | +| 1. | React Hooks: `@luno-kit/react` | Implement **22** Hooks. | |
| 211 | +| 2. | State Management System | Lightweight state management based on Zustand, supporting connection state persistence, account management, and config caching; exposed through `LunoKitProvider` for app-level state. | |
| 212 | +| 3. | Mobile Adaptation: `@luno-kit/ui` | Implement mobile wallet connection via Deeplink technology; includes device detection, UI adaptation, and auto-redirect logic. | |
| 213 | +| 4. | Theme System | Theme system based on CSS variables, supporting custom themes. | |
| 214 | +| 5. | API Integration Layer | Type-safe API layer based on Dedot; supports custom RPC calls and runtime version detection. | |
| 215 | +| 6. | Development Tools Configuration | Complete engineering setup: ESLint, TypeScript, Vitest, pnpm workspace, tsup build, etc. | |
| 216 | + |
| 217 | + |
| 218 | +## Future Plans :crystal_ball: |
| 219 | + |
| 220 | +In the short term, our focus will be on both enhancing LunoKit’s functionality and promoting it across the Polkadot ecosystem: |
| 221 | + |
| 222 | +- **More UI Components**: Add richer UI components, including advanced asset lists with NFT support and on-chain transaction history for addresses. |
| 223 | +- **Chain Support Expansion**: Add support for new parachains, improve chain switching UX. |
| 224 | +- **PolkaVM Support**: Continue developing support for PolkaVM, enabling developers to connect both Substrate-based accounts and EVM-based accounts simultaneously. This will significantly improve efficiency for those deploying Solidity DApps on PolkaHub chains. |
| 225 | +- **Extended Wallet Support**: Integrate additional wallets such as Ledger, OneKey, Mimir, Fearless, and Polkadot Vault. |
| 226 | +- **Multi-framework Frontend Support**: Extend beyond React to support frameworks such as **Vue** and **Svelte**, broadening accessibility for developers. |
| 227 | +- **Web2 Social Login Exploration**: Explore embedded wallet solutions with Web2 social login (Google, GitHub, email) for smoother onboarding. |
| 228 | +- **Ecosystem Promotion**: Increase exposure within the Polkadot ecosystem through collaboration with **OneBlock, OpenGuild, and PolkaWorld**, including launching tutorials, publishing technical articles, and conducting developer-focused courses. |
| 229 | + |
| 230 | +In the long term, our goal is to establish **LunoKit as the de facto wallet connection standard** for the Polkadot ecosystem, much like **wagmi + RainbowKit** in the EVM ecosystem. We aim to provide a unified developer experience across Substrate and EVM, multiple wallets, and frontend frameworks, making LunoKit the go-to infrastructure for DApp developers. |
| 231 | + |
| 232 | +## Additional Information :heavy_plus_sign: |
| 233 | + |
| 234 | +**How did you hear about the Grants Program?** |
| 235 | +### PolkaWorld |
0 commit comments