Toto Wallet System

A standalone, reusable Stellar wallet management system for the Toto platform. This non-custodial wallet module provides secure client-side wallet creation, management, fiat on-ramping via MoonPay, and donation capabilities.

Project Status

🎉 COMPLETE 🎉
All features have been implemented, and all tests are passing successfully. The project includes comprehensive test coverage with 46 passing tests across 9 test suites covering all components, hooks, context providers, and utility functions.

Features

• ✅ Non-custodial Stellar wallet creation and management
• ✅ XLM balance checking
• ✅ Direct XLM donations with memo support
• ✅ MoonPay integration for fiat on-ramping
• ✅ Transaction history tracking
• ✅ React hooks for easy integration

Installation

# With npm
npm install @toto/wallet-system

# With yarn
yarn add @toto/wallet-system

Publishing

For project maintainers, to publish a new version:

1. Use the release scripts to bump the version and update the changelog:

# For a patch release (bugfixes)
npm run release:patch

# For a minor release (new features, backward compatible)
npm run release:minor

# For a major release (breaking changes)
npm run release:major

2. Follow the prompts and instructions after running the release script

3. Create a new release on GitHub to trigger the automatic publishing workflow

Quick Start

import { WalletProvider, CreateWalletButton, useAccountBalance } from '@toto/wallet-system';

// Wrap your app with the provider
function App() {
  return (
    <WalletProvider
      moonPayApiKey="your_moonpay_public_api_key"
      stellarNetwork="testnet" // or 'public' for production
    >
      <WalletPage />
    </WalletProvider>
  );
}

// Use the wallet system in your components
function WalletPage() {
  const { publicKey, createWallet } = useStellarWallet();
  const { balance, isLoading, refetch } = useAccountBalance();
  
  return (
    <div>
      <h1>Toto Wallet</h1>
      
      {!publicKey ? (
        <CreateWalletButton onWalletCreated={(pk, mnemonic) => {
          console.log("Save this mnemonic securely:", mnemonic);
        }}>
          Create New Wallet
        </CreateWalletButton>
      ) : (
        <div>
          <p>Public Key: {publicKey}</p>
          <p>Balance: {isLoading ? "Loading..." : `${balance?.xlm || 0} XLM`}</p>
          <button onClick={refetch}>Refresh Balance</button>
        </div>
      )}
    </div>
  );
}

Documentation

See the integration guide for detailed instructions on how to use each component and hook.

Core Components

• WalletProvider - Context provider for wallet functionality
• CreateWalletButton - Component for creating a new wallet
• DonationModal - Modal for submitting XLM donations
• MoonPayLoader - Component for loading the MoonPay widget

Hooks

• useStellarWallet - Access the wallet context
• useAccountBalance - Check account balance
• useSubmitDonation - Submit donations
• useTransactionHistory - Get transaction history

Example Apps

See the examples directory for complete usage examples.

Development

Prerequisites

• Node.js 16+
• npm or yarn

Setup

1. Clone the repository
2. Install dependencies:

npm install

Build

npm run build

Watch for changes during development

npm run dev

Testing

npm test

Roadmap

See the roadmap progress for detailed implementation status.

License

This project is licensed under the UNLICENSED license - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin feature/my-new-feature
5. Submit a pull request

Test Coverage

The project includes comprehensive test coverage for hooks and components:

Hooks

• useAccountBalance: Tests for checking account existence, balance retrieval, and manual refresh functionality
• useSubmitDonation: Tests for donation submission, error handling, and transaction confirmation
• useTransactionHistory: Tests for automatic and manual transaction fetching, custom public key handling, and error states

Components

• CreateWalletButton: Tests for rendering, custom styling, wallet creation, loading states, and error handling
• DonationModal: Tests for form validation, submission handling, loading states, and error display
• MoonPayLoader: Tests for URL construction, error states, development mode functionality, and transaction simulation

Running Tests

npm test

To run specific tests:

npm test -- ComponentName.test.tsx

Test Environment

Tests use Jest with React Testing Library and @testing-library/react-hooks for testing custom hooks.