@ton/walletkit

@ton/walletkit

A production-ready wallet-side integration layer for TON Connect. Clean architecture, TypeScript-first, designed for building TON wallets at scale.

Overview

@ton/walletkit provides everything needed to integrate TON Connect into your wallet application:

• 🔗 TON Connect Protocol - Handle connect/disconnect/transaction/sign-data requests
• 💼 Wallet Management - Multi-wallet support with persistent storage
• 🌉 Bridge & JS Bridge - HTTP bridge and browser extension support
• 🎨 Previews for actions - Transaction emulation with money flow analysis
• 🪙 Asset Support - TON, Jettons, NFTs with metadata

For detailed SDK usage and API reference, see DOCUMENTATION.md.

Quick Install

pnpm add @ton/walletkit

Development

Setup

# Install dependencies
pnpm install

# Build packages
pnpm build

# Watch mode for development
pnpm dev

Project Structure

src/
├── core/                    # Core business logic
│   ├── TonWalletKit.ts     # Main orchestration class
│   ├── BridgeManager.ts    # Bridge connection management
│   ├── WalletManager.ts    # Wallet CRUD operations
│   └── SessionManager.ts   # Session lifecycle tracking
├── handlers/                # Event-specific handlers
│   ├── ConnectHandler.ts   # Connection requests
│   ├── TransactionHandler.ts # Transaction requests
│   └── SignDataHandler.ts  # Data signing requests
├── contracts/               # Smart contract wrappers
│   ├── JettonMaster.ts     # Jetton operations
│   └── NftItem.ts          # NFT operations
├── utils/                   # Utilities and helpers
├── types/                   # TypeScript type definitions
└── index.ts                # Public exports

Testing

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run mutation tests (quality check)
pnpm test:mutation

# View coverage report
# Open coverage/index.html in browser

Code Quality

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Quality gate (coverage + checks)
pnpm quality

Building

# Clean build artifacts
pnpm build:clean

# Build CommonJS
pnpm build:cjs

# Build ES Modules
pnpm build:esm

# Build both (recommended)
pnpm build

Architecture Principles

Modular Design

Each component has a single responsibility and can be tested in isolation:

• TonWalletKit - Orchestration layer that coordinates managers
• Managers - Core business logic (wallets, sessions, bridge)
• Handlers - Event processing (connect, transaction, sign-data)
• Utils - Pure functions (validation, storage, crypto)

Type Safety

• Full TypeScript coverage with strict mode
• Runtime validation matches compile-time types

Testing Strategy

• Unit Tests - Test individual components in isolation
• Integration Tests - Test component interactions
• Mutation Tests - Verify test suite quality with Stryker

Contributing

Adding Features

• Identify the module - Find the right place in the architecture
• Write tests first - TDD approach with unit tests
• Implement the feature - Follow existing patterns
• Update types - Ensure TypeScript types are up to date
• Document - Update DOCUMENTATION.md for public APIs

Pull Request Process

• Create a feature branch
• Write tests for your changes
• Ensure all tests pass: pnpm test
• Fix any linting issues: pnpm lint:fix
• Submit PR with clear description

Demo Wallet

The apps/demo-wallet directory contains a reference implementation showing how to integrate walletkit:

cd apps/demo-wallet
pnpm install
pnpm dev

Key files to review:

• src/stores/slices/walletSlice.ts - Kit initialization and event handlers
• src/components/modals/ - UI for connect/transaction approvals
• src/pages/SendTransaction.tsx - Programmatic transaction creation

Debugging

Enable Debug Logging

Set the environment variable before running:

DEBUG=walletkit:* pnpm dev

Common Issues

Bridge Connection Fails

• Check bridgeUrl is correct
• Verify network connectivity
• Inspect browser console for errors

Transaction Preview Empty

• Ensure wallet has TON balance for fees
• Check transaction BOC is valid
• Look for emulation errors in preview

Wallet Not Found

• Verify wallet address format
• Check wallet was added via addWallet()
• Confirm storage adapter is working

Release Process

• Update version in package.json
• Run pnpm build to create fresh build
• Run pnpm test to verify all tests pass
• Run pnpm quality to check coverage
• Commit changes and tag release
• Publish to npm: npm publish

Resources

• DOCUMENTATION.md - Complete SDK usage guide
• Demo Wallet - Reference implementation
• TON Connect Protocol - Official protocol docs

License

ISC License - see LICENSE file for details.