React Native SDK

React Native SDK for iOS and Android wallet apps. Requires Xcode/iOS Simulator or Android Studio.

Requirements: React >=18.2.0, React Native >=0.71.0, iOS >=12.0

Example App

Complete React Native example with wallet, transfers, and Lightning

Getting Started

To get started, follow the steps below.

1. Install SDK

   Install the Spark SDK packages using your package manager of choice.

   npm

   npm install @buildonspark/spark-sdk
   
2. Add Required Polyfills

   Install the required polyfills for React Native compatibility.

   npm

   npm install react-native-get-random-values @azure/core-asynciterator-polyfill buffer text-encoding
   
3. Import Polyfills at App Entry

   Critical: Import polyfills at the very top of your index.js file, BEFORE importing your app or any other modules. The crypto module will fail to load if this order is wrong.

   index.js

   // These MUST be the first imports in your app entry point
   import 'react-native-get-random-values';
   import '@azure/core-asynciterator-polyfill';
   import { Buffer } from 'buffer';
   global.Buffer = Buffer;
   
   // Now import your app
   import { AppRegistry } from 'react-native';
   import App from './App';
   import { name as appName } from './app.json';
   
   AppRegistry.registerComponent(appName, () => App);
   
4. Install Native Modules (iOS)

   For iOS, you must install the native module dependencies. This step is required for bare React Native apps.

   cd ios && pod install && cd ..
   

   If you skip this step, you’ll see errors like Cannot read property 'decryptEcies' of null when initializing the wallet.

5. Setup Wallet

   Create a wallet instance that will be used to interact with the Spark network.

   wallet.jsx

   import { SparkWallet } from "@buildonspark/spark-sdk";
   
   export const initializeWallet = async () => {
         const { wallet, mnemonic } = await SparkWallet.initialize({
           mnemonicOrSeed: "optional-mnemonic-or-seed",
           accountNumber: 0, // optional
           options: {
             network: "REGTEST" // or "MAINNET"
           }
         });
   
     console.log("Wallet initialized successfully:", mnemonic);
     return wallet;
   };
   
6. Start Building

   You’re ready to start building.

   App.jsx

   import { useState, useEffect } from "react";
   import { View, Text, Button } from "react-native";
   import { SparkWallet } from "@buildonspark/spark-sdk";
   
   export function WalletInfo() {
     const [wallet, setWallet] = useState(null);
     const [loading, setLoading] = useState(false);
   
     const createWallet = async () => {
       setLoading(true);
       try {
         const { wallet, mnemonic } = await SparkWallet.initialize({
           options: { network: "REGTEST" }
         });
         setWallet(wallet);
         console.log("Mnemonic:", mnemonic);
       } catch (error) {
         console.error("Failed to create wallet:", error);
       } finally {
         setLoading(false);
       }
     };
   
     // Note: getSparkAddress() and getBalance() are async
     const [address, setAddress] = useState("");
     const [balance, setBalance] = useState(0n);
   
     useEffect(() => {
       if (wallet) {
         wallet.getSparkAddress().then(setAddress);
         wallet.getBalance().then(b => setBalance(b.balance));
       }
     }, [wallet]);
   
     return (
       <View>
         <Text>Wallet Information</Text>
         {loading ? (
           <Text>Loading...</Text>
         ) : wallet ? (
           <View>
             <Text>Address: {address}</Text>
             <Text>Balance: {balance.toString()} sats</Text>
           </View>
         ) : (
           <Button title="Create Wallet" onPress={createWallet} />
         )}
       </View>
     );
   }
   

Initialize a Wallet

A wallet requires either a mnemonic or raw seed for initialization. The initialize() function accepts both. If no input is given, it will auto-generate a mnemonic and return it.

// Initialize a new wallet instance
	const { wallet, mnemonic } = await SparkWallet.initialize({
	  mnemonicOrSeed: "optional-mnemonic-or-seed",
	  accountNumber: 0, // optional
	  options: {
	    network: "REGTEST" // or "MAINNET"
	  }
	});

console.log("Wallet initialized successfully:", mnemonic);

Mnemonic Phrases

A mnemonic is a human-readable encoding of your wallet’s seed. It’s a 12- or 24-word phrase from the BIP-39 wordlist, used to derive the cryptographic keys that control your wallet.

Troubleshooting

Cannot read property 'decryptEcies' of null

This error occurs when native crypto modules aren’t loaded properly. Fix it by:

1. Ensure polyfills are imported first in your index.js - they must come before any other imports
2. Run pod install in your ios/ directory for iOS builds
3. Rebuild your app completely (not just a hot reload)

# iOS
cd ios && pod install && cd ..
npx react-native run-ios

# Android
npx react-native run-android

Wallet initialization fails silently

Make sure you’re awaiting the initialize() call and handling errors:

try {
  const { wallet, mnemonic } = await SparkWallet.initialize({
    options: { network: "MAINNET" }
  });
} catch (error) {
  console.error("Wallet init failed:", error);
}