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

Testnet Testing

Before deploying to production, it's crucial to thoroughly test the wallet system on Stellar's testnet:

1. Run the automated testnet test script:

   node scripts/testnet-testing.js

   This script performs end-to-end testing of wallet creation, funding via Friendbot, balance checking, payments, and transaction history.

2. Use the Testnet Dashboard:

   # First build the project
   npm run build
      
   # Then run the testnet dashboard (requires a React environment)
   cd examples/testnet-dashboard
   npm start

   The dashboard provides a UI for manually testing all wallet functions in the testnet environment.

3. Testnet Configuration: Edit scripts/testnet.config.js to customize your testnet testing parameters.

4. Generating Test Reports: After testing, fill out the report template in docs/testnet_report_template.md to document test results.

5. Stellar Testnet Resources:

   • Stellar Laboratory - Create and manage testnet accounts
   • Friendbot - Fund testnet accounts with free XLM
   • Testnet Explorer - Explore testnet transactions and accounts

Important: Always ensure that your application clearly indicates when it's operating in testnet mode to prevent confusion with real funds.

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.

Making Donations / Topping Up a Guardian's Wallet

To allow users to donate or top up a guardian's wallet, use the createDonation function. This generates a MoonPay URL for the guardian's public key, which you can use in an iframe, link, or redirect. Users do not need their own wallets.

Example Usage

import { createDonation } from './src/utils/moonpay';

const url = createDonation({
  guardianPublicKey: 'GUARDIAN_PUBLIC_KEY',
  apiKey: 'YOUR_MOONPAY_API_KEY',
  baseUrl: 'https://buy.moonpay.com', // optional
  defaultCurrency: 'usd', // optional
  baseCurrencyAmount: 50, // optional
  email: '[email protected]' // optional
});
// Use this URL in an iframe, link, or redirect

This replaces the previous user-facing donation modal and MoonPayLoader component for donation flows.