LunoKit: Developer-friendly Web3 account connection infrastructure

I. Project Overview

LunoKit (GitHub) is the core product developed by Lunolab, dedicated to building an open-source, customizable, and developer-friendly Web3 account connection infrastructure for the Polkadot ecosystem. It encapsulates connection state management, account abstraction, chain switching, and session restoration, significantly lowering integration barriers.

For developers building DApps on Polkadot SDK-based chains—especially on the upcoming Polkadot Hub—it takes only 10 minutes to integrate comprehensive wallet login functionality with a polished UI experience.

---

II. Core Pain Points

1. High Integration Barrier for Multiple Wallets
   • The ecosystem includes various wallets (polkadot.js, Talisman, SubWallet, NovaWallet, etc.), each with different integration methods, scattered documentation, and lacking type hints, leading to long development cycles and high error rates.
   • LunoKit Advantage: Unified TypeScript-first SDK and React Hooks enable standardized integration with mainstream wallets in under 10 minutes, greatly reducing development cost.
2. Fragmented Account State Management
   • Account formats differ across wallets, and logic for chain switching, session restoration, and authorization status is scattered, requiring developers to manually maintain multiple state management setups.
   • LunoKit Advantage: Unified account model and state management abstraction (useLunoAccount, useSwitchChain, useSessionRestore) allow global reuse with a single integration.
3. Repetitive UI Component Development
   • From connect modals and asset panels to network switchers, DApps often have to custom build UI components, making it difficult to ensure accessibility and consistency.
   • LunoKit Advantage: Offers a ready-to-use, fully customizable UI component suite including connect buttons, account modals, asset panels, and network switchers.
4. Complex On-Chain Data Subscription and Caching
   • Polkadot's subscription interfaces (derive, RPC, storage queries) are diverse; developers need to build their own caching and retry logic, which can lead to performance bottlenecks.
   • LunoKit Advantage: Built-in TanStack Query support with universal subscription hook (useSubscription) provides efficient, secure data subscription with no extra configuration.
5. Lack of Comprehensive Documentation and Examples
   • Official examples are often limited to isolated use cases, with incomplete type hints, resulting in a steep learning curve.
   • LunoKit Advantage: Full API documentation, multi-framework integration examples, and complete TypeScript type support help developers get started quickly.
6. Polkadot Hub Compatibility
   • With the launch of Polkadot Hub, more DApps will need to simultaneously handle wallet connections for both Substrate and EVM addresses—a critical yet highly repetitive task for developers.
   • LunoKit Advantage: Will support EVM chains post-Polkadot Hub launch, enabling developers to focus on core logic while LunoKit handles account connectivity.

---

III. Technical Architecture & Developer Usage

1. @luno-kit/core Core Abstraction Layer

• Unified connector interface and type system
• Chain configuration, account management, signer abstraction
• Standardized integration with multiple wallet connectors

2. @luno-kit/react React Integration Layer

• Built with React 18+ and TypeScript
• Lightweight reactive state management via Zustand
• Integrated TanStack Query for data caching and synchronization
• Integrated Dedot for blockchain interaction, with 20+ essential hooks and smart reconnection logic

3. @luno-kit/ui UI Component Layer

• Built with React 18+ and TypeScript
• Tailwind CSS 4.x for modern styling
• Integrated with Radix UI for accessibility
• Plug-and-play wallet connection components
• Fully customizable theming system

Basic setup

import { LunoKitProvider, ConnectButton } from '@luno-kit/ui'
import { createConfig, defineChain, kusama, polkadot, polkadotjs, subwallet, westend, paseo } from '@luno-kit/react'
import '@luno-kit/ui/dist/styles.css'

const config = createConfig({
  appName: 'My Luno App',
  chains: [polkadot, kusama, westend, paseo],
  connectors: [polkadotjs(), subwallet()],
  autoConnect: true,
})

/* 
// Custom chain example:
const customChain = defineChain({
  genesisHash: '0x1234...', // Your chain's genesis hash
  name: 'My Custom Chain',
  nativeCurrency: { name: 'Custom Token', symbol: 'CUSTOM', decimals: 12 },
  rpcUrls: { webSocket: ['wss://my-chain-rpc.example.com'] },
  ss58Format: 42,
  blockExplorers: { default: { name: 'Explorer', url: 'https://explorer.example.com' } },
  chainIconUrl: 'https://example.com/icon.png',
  testnet: true
})

// Then use: chains: [customChain]
*/

function App() {
  return (
    <LunoKitProvider config={config}>
      <ConnectButton />
    </LunoKitProvider>
  )
}

Using with React Hooks

import { LunoKitProvider } from '@luno-kit/ui'
import { useAccount, useBalance, useConnect, ConnectionStatus } from '@luno-kit/react'

function WalletInfo() {
  const { account } = useAccount()
  const { data: balance } = useBalance({ address });
  const { connect, connectors, status } = useConnect()

  if (status !== ConnectionStatus.Connected) {
    return (
      <button onClick={() => connect({ connectorId: connectors[0].id })}>
        Connect Wallet
      </button>
    )
  }

  return (
    <div>
      <div>Account: {account?.name}</div>
      <div>Address: {account?.address}</div>
      <div>Transferable Balance: {balance?.formattedTransferable}</div>
      <div>Total Balance: {balance?.formattedTotal}</div>
    </div>
  )
}

function App() {
  return (
    <LunoKitProvider config={config}>
      <WalletInfo />
    </LunoKitProvider>
  )
}

---

IV. Core Functional Features

4.1 Connection Management

• useConnect: Manage multi-wallet connections
• useDisconnect: Secure disconnection
• useActiveConnector: Track current active connector
• useConnectors: List of available connectors
• useStatus: Monitor connection status

4.2 Account Management

• useAccount: Info on the active account
• useAccounts: List of all connected accounts
• useBalance: Balance queries

4.3 Chain Information Queries

• useChain: Current chain info
• useChains: List of supported chains
• useSwitchChain: Switch chains
• useRuntimeVersion: Runtime version
• useBlockNumber: Real-time block height subscription
• useSs58Format: SS58 address format

4.4 API Management

• useApi: Dedot API instance management
• useConfig: Configuration management

4.5 General Subscription System

• useSubscription: Subscribe to any Dedot API, support custom data transformation and intelligent retries

4.6 Transaction Operations

• useSendTransaction: Manage transaction lifecycle and receipt parsing
• useSignMessage: Sign messages
• useSigner: Manage signers

4.7 State Management

• Built-in caching and retry via TanStack Query
• Smart loading state and error handling

---

V. Team Background

Lunolab is composed of two experienced developers with over 5 years of dedicated expertise in blockchain technology, and a long-standing focus on the Substrate and Polkadot ecosystems. Our past experience includes contributing to the development of a BTC Layer 2 public blockchain based on Substrate, incorporating modules such as EVM compatibility, cross-chain bridges, and blockchain explorers.

We also led the development of the comprehensive DeFi solution OmniBTC, which includes OmniSwap, a cross-chain trading aggregator supporting over 40 public chains and more than 20 cross-chain bridges, achieving a cumulative trading volume exceeding $2 billion. Additionally, we developed OmniLending, a cross-chain lending platform with a total value locked (TVL) surpassing $10 million.

Moreover, our team participated in the technical development of ComingChat, a Web3 social application that has surpassed 10 million registered users.

Currently, our team is primarily focused on infrastructure development within the Substrate and Polkadot ecosystems, equipped with robust multi-chain expertise and extensive experience in frontend infrastructure design.

• Cris (X): Product Manager, responsible for requirement analysis, UI/UX design, and contributing to partial UI development.

• Brian (github.com/wbh1328551759): Core developer, responsible for core technical implementation.

---

VI. Budget

Module	Estimated Hours	Cost
Wallet integration (polkadot.js, Talisman, SubWallet, Nova, PolkaGate)	100 hrs	$6,000
Core abstraction layer (@luno-kit/core)	140 hrs	$8,400
React Hooks (20+ hooks like useLunoConnect)	160 hrs	$9,600
UI Component Library (v1)	100 hrs	$6,000
Theme system (light/dark mode support)	40 hrs	$2,400
State management & session persistence	80 hrs	$4,800
Network switching & chain management	40 hrs	$2,400
Documentation	20 hrs	$1,200
Demo preview & site deployment	60 hrs	$3,600
UI design drafts	40 hrs	$2,400
Project management & testing	40 hrs	$2,400
Total	820 hrs	$49,200

The budget is based on two full-time developers over a 3-month development cycle.

---

VII. UI Preview

The following screenshots and mockups demonstrate key modules such as wallet connection entry, asset panels, and account modals, reflecting the LunoKit design system and UX principles.

UI Preview

Preview Demo: https://demo.lunolab.xyz/

This is a temporary demo and not the final delivery version.

---

VIII. Future Roadmap

• LunoKit will natively support both Substrate and EVM chains, aligning with Polkadot Hub's EVM compatibility. Developers can save time and focus on core business logic while LunoKit handles account connectivity.
• LunoKit will develop an interactive Playground page that provides a visual configuration interface, allowing developers to choose login methods, customize UI appearance, and configure component behaviors in real time. It will support live wallet connection previews and exportable code snippets, greatly improving integration speed and developer experience.
• LunoKit might explore supporting embedded wallets with Web2 social login (e.g., Google, GitHub, email) in the future to provide a smoother onboarding experience.

IX. Contact Us

• lunolab1@gmail.com
• https://x.com/luno_lab