Celo Gasless Wallet SDK

A comprehensive TypeScript/JavaScript SDK for building gasless applications on Celo with USDC support, enabling developers to sponsor transaction fees for their users.

Features

• 🏦 Celo Wallet Management: Create and manage Celo-compatible wallets
• 💰 USDC Integration: Full support for Celo's native USDC stablecoin
• ⛽ Gas Sponsorship: Sponsor transaction fees for your users
• 🔄 Transaction Builder: Prepare, sign, and send gasless transactions
• 🌐 Multi-Network Support: Works with Celo Mainnet and Alfajores Testnet
• 📊 Balance Checks: Query USDC and native token balances

Installation

npm install celo-gasless-wallet
# or
yarn add celo-gasless-wallet

Prerequisites

• Node.js v16+
• Celo account with testnet funds (for development)
• Basic understanding of Ethereum/Celo transactions

Quick Start

import { CeloGaslessWallet } from 'celo-gasless-wallet';

// Initialize with Alfajores testnet
const gaslessWallet = new CeloGaslessWallet({
  network: 'alfajores'
});

// Create a new user wallet
const userWallet = gaslessWallet.createWallet();
console.log('User wallet created:', userWallet.address);

// Sponsor a USDC transfer (in a real app, keep sponsor key secure!)
const txHash = await gaslessWallet.sponsoredUSDCTransfer({
  senderPrivateKey: userWallet.privateKey,
  to: '0xRecipientAddress',
  amount: '10.50', // USDC
  sponsorPrivateKey: process.env.SPONSOR_PRIVATE_KEY
});

console.log('Transaction completed:', txHash);

Core Concepts

Gas Sponsorship Model

This SDK implements a two-step sponsorship model:

1. Sponsor Preparation: The sponsor (dApp) sends enough CELO to cover gas fees
2. User Transaction: The user submits their USDC transfer using the provided gas

This approach maintains security while removing the need for users to hold CELO.

API Reference

CeloGaslessWallet(config?)

Constructor options:

interface Config {
  network?: 'mainnet' | 'alfajores'; // Default: 'alfajores'
  rpcUrl?: string; // Optional custom RPC endpoint
}

Wallet Management

createWallet(): Wallet

Creates a new random wallet.

Returns:

interface Wallet {
  address: string;
  privateKey: string;
  mnemonic?: string;
}

Balance Checks

getUSDCBalance(address: string): Promise<string>

Gets USDC balance for an address.

getNativeBalance(address: string): Promise<string>

Gets CELO balance for an address.

Transaction Methods

prepareSponsoredTransaction(params): Promise<PreparedTx>

Prepares a USDC transfer for sponsorship.

Parameters:

interface TransactionParams {
  from: string;
  to: string;
  value: string; // USDC amount
  sponsorPrivateKey?: string;
}

Returns:

interface PreparedTx {
  unsignedTx: ethers.providers.TransactionRequest;
  estimatedGas: string;
  estimatedGasCost: string;
  sponsorAddress?: string;
}

sponsorAndSendTransaction(unsignedTx, sponsorPrivateKey): Promise<string>

Sponsors and sends a prepared transaction.

sponsoredUSDCTransfer(params): Promise<string>

Complete sponsored transfer flow.

Parameters:

interface TransferParams {
  senderPrivateKey: string;
  to: string;
  amount: string;
  sponsorPrivateKey: string;
}

Security Considerations

1. Private Key Management:

   • Never hardcode private keys
   • Use environment variables or secure key management services
   • Consider using wallet connect for user interactions

2. Gas Estimation:

   • Always estimate gas requirements
   • Add buffer for unpredictable conditions

3. Error Handling:

   • Implement comprehensive error handling
   • Provide user feedback for failed transactions

Advanced Usage

Custom Transaction Types

Extend sponsorship to other transaction types:

const customTx = await gaslessWallet.prepareSponsoredTransaction({
  from: userAddress,
  to: contractAddress,
  data: contractInterface.encodeFunctionData('methodName', [params]),
  sponsorPrivateKey
});

const txHash = await gaslessWallet.sponsorAndSendTransaction(
  customTx.unsignedTx,
  sponsorPrivateKey
);

Multi-Sponsor Patterns

Implement rotating sponsors for load balancing:

const sponsors = [
  process.env.SPONSOR_1_KEY,
  process.env.SPONSOR_2_KEY
];

const currentSponsor = sponsors[Math.floor(Math.random() * sponsors.length)];

Troubleshooting

Common Issues

1. Insufficient Sponsor Balance:

   • Ensure sponsor has enough CELO for gas
   • Check estimatedGasCost before sending

2. Transaction Timeouts:

   • Implement retry logic
   • Adjust gas prices dynamically

3. Network Congestion:

   • Monitor network status
   • Consider using fee market APIs

Contributing

We welcome contributions! Please see our Contribution Guidelines.

License

MIT

Support

For support, please open an issue on our GitHub repository.

Built with ❤️ by the Celo developer community