@novastera-oss/nitro-metamask

Native mobile MetaMask wallet integration for React Native. Part of Novastera's modern CRM and ERP platform ecosystem, designed for businesses that handle cryptocurrency and blockchain transactions.

Requirements

• React Native v0.76.0 or higher
• Node 18.0.0 or higher

[!IMPORTANT]
To Support Nitro Views you need to install React Native version v0.78.0 or higher.

Installation

npm install @novastera-oss/nitro-metamask react-native-nitro-modules

Android Configuration

Required: Add a deep link intent filter to enable MetaMask to return to your app after connecting or signing.

File: android/app/src/main/AndroidManifest.xml

Add this inside your MainActivity <activity> tag:

<activity
  android:name=".MainActivity"
  android:launchMode="singleTask"
  ...>
  <!-- Existing intent filters -->
  
  <!-- Deep link intent filter for MetaMask callback -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="nitrometamask" android:host="mmsdk" />
  </intent-filter>
</activity>

Important:

• Ensure android:launchMode="singleTask" is set on your MainActivity (recommended for deep linking)
• This allows MetaMask to return to your app after the user approves the connection or signature

iOS Configuration

For Expo projects: The package includes an Expo config plugin that automatically adds the required AppDelegate code. Just add the plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": ["@novastera-oss/nitro-metamask"]
  }
}

The plugin will automatically:

• Add the import MetaMaskSDK statement
• Add the application(_:open:options:) method to handle MetaMask deep links
• Work with both Swift and Objective-C AppDelegate files

For bare React Native projects: Add deep link handling manually in your AppDelegate.swift (or AppDelegate.m for Objective-C):

File: ios/YourAppName/AppDelegate.swift

import MetaMaskSDK

// ... existing AppDelegate code ...

// Handle deep links from MetaMask wallet
// MetaMask returns to the app via deep link after signing/connecting
func application(
  _ app: UIApplication,
  open url: URL,
  options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
  // Check if this is a MetaMask deep link (host="mmsdk")
  if let components = URLComponents(url: url, resolvingAgainstBaseURL: true),
     components.host == "mmsdk" {
    // Handle MetaMask deep link return
    MetaMaskSDK.shared.handleUrl(url)
    return true
  }
  
  // Handle other deep links (e.g., React Native Linking)
  return false
}

Info.plist: The URL scheme is automatically detected from your Info.plist CFBundleURLSchemes configuration. Ensure you have a URL scheme configured (e.g., nitrometamask).

Usage

import { NitroMetamask } from '@novastera-oss/nitro-metamask';

// Optional: Configure dapp URL and deep link scheme
// If not called, defaults to "https://novastera.com" and auto-detects deep link scheme
// This URL is ONLY used for SDK validation - the deep link return is handled automatically
NitroMetamask.configure('https://yourdomain.com', 'nitrometamask'); // Optional

// Connect to MetaMask
const connectResult = await NitroMetamask.connect();
console.log('Connected:', connectResult.address, 'Chain:', connectResult.chainId);

// Sign a message (requires connection first)
const signature = await NitroMetamask.signMessage('Hello from my app!');

// Connect and sign in one call (convenience method)
// This constructs a JSON message with nonce and exp, then signs it
// Returns signature, address, and chainId together
const nonce = 'random-nonce-123';
const exp = BigInt(Date.now() + 42000); // 42 seconds from now (use BigInt for timestamp)
const result = await NitroMetamask.connectSign(nonce, exp);
console.log('Signature:', result.signature);
console.log('Address:', result.address);
console.log('Chain ID:', result.chainId);

// Get current address and chainId (useful if you need to check after other operations)
const address = await NitroMetamask.getAddress();
const chainId = await NitroMetamask.getChainId();

Use Cases

This library is ideal for:

• Crypto-friendly CRM/ERP systems that need to authenticate users via MetaMask
• DeFi applications requiring secure wallet connections
• NFT marketplaces needing signature verification
• Web3 mobile apps that integrate with blockchain networks

How Deep Linking Works

Important: The MetaMask SDK requires a valid HTTP/HTTPS URL for DappMetadata.url validation, but this is separate from the deep link that returns to your app.

Two separate things:

1. DappMetadata.url (optional, configurable):

   • Used only for SDK validation - the SDK checks it's a valid HTTP/HTTPS URL
   • Defaults to "https://novastera.com" if not configured
   • You can call NitroMetamask.configure('https://yourdomain.com') if you have a website
   • If you don't have a website, the default works fine - it's just for validation
   • Reference

2. Deep Link Return (automatic or configurable):

   • Automatically detected from your AndroidManifest.xml intent filter
   • The SDK reads <data android:scheme="..." android:host="mmsdk" /> and uses it to return to your app
   • You can also explicitly provide the scheme via configure(): NitroMetamask.configure('https://yourdomain.com', 'nitrometamask')
   • This is what actually makes MetaMask return to your app after operations
   • If not explicitly configured, the library will attempt to auto-detect it from your manifest

Summary:

• The configure() URL is just for SDK validation (you can use the default if you don't have a website)
• The deep link scheme can be auto-detected or explicitly provided via configure()
• Your app will return correctly as long as the manifest is configured properly

About Novastera

Novastera is a modern CRM and ERP platform designed to streamline business operations and customer relationship management. Built for businesses operating in the Web3 space, Novastera provides comprehensive support for cryptocurrency transactions, blockchain integrations, and digital asset management.

This library is part of Novastera's open-source ecosystem, providing native mobile MetaMask wallet integration for React Native applications. Whether you're building a DeFi application, NFT marketplace, or any Web3-enabled mobile app, this library provides the tools you need to integrate MetaMask wallet functionality seamlessly.

Key Features:

• Native mobile MetaMask wallet support for iOS and Android
• Seamless deep linking integration
• Secure authentication and message signing
• Built with Nitro Modules for optimal performance
• Crypto-friendly CRM and ERP platform integration

Learn more about Novastera: https://novastera.com/resources

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.