Oathstone

Multi-chain blockchain wallet management library for React and Next.js applications.

Installation

npm install oathstone
# or
yarn add oathstone
# or
pnpm add oathstone

Features

• 🔐 Create Ethereum-compatible wallets
• 💰 Check balances across multiple networks
• 💸 Transfer native and ERC-20 tokens
• 🌐 Multi-chain support (Ethereum, Celo, etc.)
• ⚛️ React hooks for easy integration
• 📦 TypeScript support

Quick Start

React Hook Usage

import { useOathstone } from 'oathstone/react';

const config = {
  networks: {
    celo: {
      environment: 0, // 0 = testnet, 1 = mainnet
      rpcUrl: {
        testnet: 'https://forno.celo-sepolia.celo-testnet.org',
        mainnet: 'https://forno.celo.org'
      },
      tokens: {
        USD: {
          contractAddress: '0xd0A1B537e1012F3ec148c8ccf108ab4A687820C9',
          symbol: 'USD',
          abi: [/* your token ABI */]
        }
      }
    }
  }
};

function WalletComponent() {
  const { createWallet, getBalance, transfer, isInitialized, isLoading, error } = useOathstone(config);

  const handleCreateWallet = () => {
    const wallet = createWallet();
    console.log('New wallet:', wallet);
  };

  const handleGetBalance = async () => {
    const balances = await getBalance('0xYourPrivateKey');
    console.log('Balances:', balances);
  };

  const handleTransfer = async () => {
    const result = await transfer({
      privateKey: '0xYourPrivateKey',
      toAddress: '0xRecipientAddress',
      amount: '1.0',
      type: 'native'
    });
    console.log('Transfer result:', result);
  };

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!isInitialized) return <div>Initializing...</div>;

  return (
    <div>
      <button onClick={handleCreateWallet}>Create Wallet</button>
      <button onClick={handleGetBalance}>Get Balance</button>
      <button onClick={handleTransfer}>Transfer</button>
    </div>
  );
}

Direct Usage (without React)

import { Oathstone } from 'oathstone';

const config = {
  networks: {
    celo: {
      environment: 0,
      rpcUrl: {
        testnet: 'https://forno.celo-sepolia.celo-testnet.org',
        mainnet: 'https://forno.celo.org'
      }
    }
  }
};

const oathstone = new Oathstone(config);
await oathstone.initialize();

// Create wallet
const wallet = oathstone.createWallet();
console.log(wallet);

// Get balance
const balances = await oathstone.getBalance('0xYourPrivateKey');
console.log(balances);

// Transfer
const result = await oathstone.transfer({
  privateKey: '0xYourPrivateKey',
  toAddress: '0xRecipientAddress',
  amount: '1.0',
  type: 'native'
});
console.log(result);

API Reference

useOathstone(config)

React hook that provides wallet management functionality.

Returns:

• oathstone: Oathstone instance
• isInitialized: Boolean indicating if the library is ready
• isLoading: Boolean indicating if an operation is in progress
• error: Error message if any operation failed
• createWallet(): Function to create a new wallet
• getBalance(privateKey): Function to get balances
• transfer(params): Function to transfer tokens

Oathstone Class

Methods

• initialize(config?): Initialize the instance with configuration
• createWallet(): Create a new wallet with address, private key, and mnemonic
• getBalance(privateKey): Get balances across all configured networks
• transfer(params): Transfer native or token assets

Transfer Parameters

{
  privateKey: string;      // Sender's private key
  toAddress: string;       // Recipient address
  amount: string;          // Amount to transfer
  type: 'native' | 'token'; // Transfer type
  network?: string;        // Optional: specific network
  tokenName?: string;      // Required for token transfers
}

Configuration

The configuration object defines networks and tokens:

{
  networks: {
    [networkName: string]: {
      environment: 0 | 1;  // 0 = testnet, 1 = mainnet
      rpcUrl: {
        testnet: string;
        mainnet: string;
      };
      tokens?: {
        [tokenName: string]: {
          contractAddress: string;
          symbol: string;
          abi: any[];
        };
      };
    };
  };
}

Security Notes

⚠️ Never expose private keys in client-side code in production!

This library is designed for:

• Development and testing environments
• Server-side Next.js API routes
• Secure backend services
• Educational purposes

For production applications, always:

• Store private keys securely on the server
• Use wallet connection libraries (WalletConnect, MetaMask, etc.)
• Implement proper key management solutions

License

MIT