@civic/react-native-auth-web3

Web3 SDK for React Native - Enable Solana blockchain functionality in your React Native apps with Civic Auth embedded wallets.

⚠️ Early Access: This SDK is currently in early access and subject to change.

Installation

Install the SDK and its peer dependencies:

# npm
npm install @civic/react-native-auth-web3 @solana/web3.js

# yarn
yarn add @civic/react-native-auth-web3 @solana/web3.js

# pnpm
pnpm add @civic/react-native-auth-web3 @solana/web3.js

Native Setup

Android Configuration

Add the following to your android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 26  // Required minimum SDK version

        ...

        // Add manifest placeholders for embedded wallet integration
        manifestPlaceholders = [
            metakeepDomain: "*.auth.metakeep.xyz",
            metakeepScheme: <YourAppSchema>
        ]
    }
}

iOS Configuration

Requirements:

• iOS 14.0 or higher
• Xcode 14.0 or higher
• Swift 5.0 or higher

Step 1: Add URL Type

1. Navigate to the Info tab of your app target settings in Xcode
2. In the URL Types section, click the ＋ button to add a new URL
3. Enter the following values:
   • Identifier: metakeep
   • URL Schemes: $(PRODUCT_BUNDLE_IDENTIFIER)

Step 2: Handle Callback URLs

Add the following code to your ios/<YourAppName>/AppDelegate.swift:

public override func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {

    ...

    if url.absoluteString.lowercased().contains("metakeep") {
        MetaKeep.companion.resume(url: url.absoluteString)
        return true
    }

   ...

}

Quick Start

import { useWeb3Client } from "@civic/react-native-auth-web3";

const web3Config = {
  solana: {
    endpoint: "https://api.devnet.solana.com", // Your RPC endpoint
  },
};

// Initialize the Web3 client with user's ID token
const web3Client = useWeb3Client(web3Config, idToken);

// Create wallets after login
if (!web3Client?.solana) {
  await web3Client?.createWallets();
}

API Reference

useWeb3Client Hook

Returns a Web3Client object for interacting with blockchain networks.

interface Web3Client {
  solana: SolanaWeb3Client; // Solana wallet operations
  connected: boolean; // Connection status
  createWallets(): Promise<Wallets>; // Create embedded wallets
  disconnect(): Promise<void>; // Disconnect and cleanup
}

SolanaWeb3Client Methods

interface SolanaWeb3Client {
  readonly address: string; // Wallet public key

  // Core transaction methods
  sendTransaction(address: string, amount: number): Promise<string>;
  signTransaction(transaction: Transaction, reason: string): Promise<Buffer>;
  signMessage(message: string, reason: string): Promise<string>;

  // Utility methods
  getBalance(): Promise<number | undefined>;
  disconnect(): Promise<void>;
}

Usage Examples

Sending SOL

// Simple transfer - Send 0.5 SOL
const txHash = await web3Client?.solana?.sendTransaction(
  "RecipientPublicKeyHere",
  0.5, // Amount in SOL
);
console.log(`Transaction: ${txHash}`);

Custom Transactions

import {
  Connection,
  Transaction,
  SystemProgram,
  PublicKey,
} from "@solana/web3.js";

const connection = new Connection(web3Config.solana.endpoint);

// Build custom transaction
const transaction = new Transaction().add(
  SystemProgram.transfer({
    fromPubkey: new PublicKey(web3Client.solana.address),
    toPubkey: new PublicKey(recipientAddress),
    lamports: 0.001 * 1e9, // 0.001 SOL in lamports
  }),
);

// Sign the transaction
const signature = await web3Client?.solana?.signTransaction(
  transaction,
  "Approve transfer", // Reason shown to user
);

// Add signature and send
transaction.addSignature(new PublicKey(web3Client.solana.address), signature);
const txHash = await connection.sendRawTransaction(transaction.serialize());

Checking Balance

import { Connection, PublicKey, LAMPORTS_PER_SOL } from "@solana/web3.js";

const connection = new Connection(web3Config.solana.endpoint);
const balanceLamports = await connection.getBalance(
  new PublicKey(web3Client.solana.address),
);
const balanceSOL = balanceLamports / LAMPORTS_PER_SOL;
console.log(`Balance: ${balanceSOL} SOL`);

Signing Messages

const message = "Verify wallet ownership";
const signature = await web3Client?.solana?.signMessage(
  message,
  "Sign to verify your wallet", // Shown to user
);
console.log(`Signature: ${signature}`);

Complete Integration Example

For a complete example showing authentication with Civic Auth and wallet creation, see our example implementation.

How It Works

1. Authentication: Users authenticate with Civic Auth
2. ID Token: Receive a JWT proving user identity
3. Wallet Creation: SDK creates a non-custodial embedded wallet linked to the user's Civic account
4. Blockchain Operations: Use the wallet for transactions, signing, and other Web3 operations

The wallet creation process requires a valid ID token from Civic Auth. This ensures only authenticated users can create wallets, with each wallet uniquely tied to a specific user account.

Crypto Polyfill

The SDK automatically includes a crypto polyfill using expo-crypto to provide cryptographic operations required by Solana in React Native environments.

Support

• 📖 Documentation