NodeFlow SDK

NodeFlow SDK is a React library that enables seamless asset bridging between EVM chains and the Bitcoin Lightning Network.

Features

• Cross-Chain Bridge: Bridge assets between EVM chains and Lightning Network
• Multi-Chain Support: Base, BSC, and more
• Wallet Integration: Built-in WalletConnect support
• Dynamic Configuration: Auto-detects supported networks from API
• Responsive UI: Dark theme with customizable modal

Installation

yarn add @lnfi-network/nodeflow-sdk
# or
npm install @lnfi-network/nodeflow-sdk

Peer dependencies (wagmi, viem, @reown/appkit, etc.) will be installed automatically.

Configuration

| Item | Value | Description | | :--- | :--- | :--- | | Project ID | Get from WalletConnect | Required for wallet connection | | Dev API URL | <API_BASE_URL> | Development/Testnet | | Prod API URL | (Contact support) | Production |

Quick Start

import { 
  NodeFlowProvider, 
  NodeFlowModal, 
  nodeFlowSend, 
  nodeFlowReceive,
  useNodeFlowPairs  // Hook to get available asset pairs
} from '@lnfi-network/nodeflow-sdk';

function App() {
  return (
    <NodeFlowProvider 
      projectId="your-walletconnect-project-id" 
      apiUrl="<API_BASE_URL>"
    >
      <NodeFlowModal />
      <MyBridgeUI />
    </NodeFlowProvider>
  );
}

function MyBridgeUI() {
  // Get available trading pairs dynamically - no hardcoded asset IDs needed!
  const { pairs, defaultAssetId, isReady } = useNodeFlowPairs();
  
  if (!isReady) return <div>Loading...</div>;

  return (
    <div>
      {/* Lightning → EVM: Get tokens by paying LN invoice */}
      <button onClick={() => nodeFlowSend({
        assetId: defaultAssetId,  // Use dynamic asset ID
        amount: 1000,             // Amount in sats
        onSuccess: (result) => console.log('Success!', result)
      })}>
        Get Tokens (Pay Lightning)
      </button>
      
      {/* EVM → Lightning: Pay LN invoice with tokens */}
      <button onClick={() => nodeFlowReceive({
        assetId: defaultAssetId,
        invoice: "lnbc...",       // Lightning invoice to pay
        onSuccess: (result) => console.log('Paid!', result)
      })}>
        Pay Invoice (Use Tokens)
      </button>
    </div>
  );
}

How It Works

Lightning → EVM (Get Tokens)

User pays a Lightning invoice to receive EVM tokens.

┌─────────────────────────────────────────────────────────────────────────────┐
│                    Lightning → EVM (nodeFlowSend)                           │
└─────────────────────────────────────────────────────────────────────────────┘

    User                           SDK                           LSP Node
      │                              │                               │
      │  nodeFlowSend({              │                               │
      │    assetId, amount           │                               │
      │  })                          │                               │
      ├─────────────────────────────►│                               │
      │                              │                               │
      │                              │  Request Quote & Invoice      │
      │                              ├──────────────────────────────►│
      │                              │  ◄── { invoice }              │
      │                              │                               │
      │  Show Invoice QR             │                               │
      ◄──────────────────────────────│                               │
      │                              │                               │
      │  User pays via LN wallet     │                               │
      ├──────────────────────────────┼──────────────────────────────►│
      │                              │                               │
      │                              │  LSP releases tokens on-chain │
      │                              │  ◄──────────────────────────────
      │                              │                               │
      │  ✅ Tokens received!          │                               │
      ◄──────────────────────────────│                               │

EVM → Lightning (Pay Invoice)

User pays a Lightning invoice using their EVM tokens.

┌─────────────────────────────────────────────────────────────────────────────┐
│                    EVM → Lightning (nodeFlowReceive)                        │
└─────────────────────────────────────────────────────────────────────────────┘

    User                           SDK                           LSP Node
      │                              │                               │
      │  nodeFlowReceive({           │                               │
      │    assetId, invoice          │                               │
      │  })                          │                               │
      ├─────────────────────────────►│                               │
      │                              │                               │
      │  Show quote & confirm        │                               │
      ◄──────────────────────────────│                               │
      │                              │                               │
      │  Approve & Deposit tokens    │                               │
      ├─────────────────────────────►│                               │
      │                              │                               │
      │                              │  Lock tokens in contract      │
      │                              ├──────────────────────────────►│
      │                              │                               │
      │                              │  LSP pays LN invoice          │
      │                              │  ◄──────────────────────────────
      │                              │                               │
      │  ✅ Invoice paid!             │                               │
      ◄──────────────────────────────│                               │

API Reference

Components

<NodeFlowProvider>

Main provider component. Wrap your app with this.

| Prop | Type | Required | Description | | :--- | :--- | :--- | :--- | | projectId | string | ✅ | WalletConnect Project ID | | apiUrl | string | ✅ | NodeFlow API URL | | themeMode | 'dark' \| 'light' | - | Theme mode (default: 'dark') | | customNetworks | Network[] | - | Custom network configuration |

<NodeFlowModal>

Modal component for transaction UI. Add once inside the provider.

Functions

nodeFlowSend(options)

Lightning → EVM: Get tokens by paying a Lightning invoice.

| Option | Type | Description | | :--- | :--- | :--- | | assetId | string | Asset ID (get from useNodeFlowPairs) | | amount | number | Amount in satoshis | | onProgress | (step, data) => void | Progress callback | | onSuccess | (result) => void | Success callback | | onError | (error) => void | Error callback |

Progress steps: 'init' → 'signature' → 'deposit' → 'pending' → 'complete'

const result = await nodeFlowSend({
  assetId: defaultAssetId,
  amount: 1000,
  onProgress: (step) => console.log('Step:', step),
  onSuccess: (result) => console.log('Success:', result),
});

nodeFlowReceive(options)

EVM → Lightning: Pay a Lightning invoice using tokens.

| Option | Type | Description | | :--- | :--- | :--- | | assetId | string | Asset ID (get from useNodeFlowPairs) | | invoice | string | Lightning invoice to pay | | onProgress | (step, data) => void | Progress callback | | onSuccess | (result) => void | Success callback | | onError | (error) => void | Error callback |

Progress steps: 'init' → 'approve' → 'deposit' → 'complete'

const result = await nodeFlowReceive({
  assetId: defaultAssetId,
  invoice: 'lnbc...',
  onSuccess: (result) => console.log('Paid:', result),
});

Hooks

useNodeFlowPairs()

Get available trading pairs for the current chain.

const { 
  pairs,          // All available pairs
  defaultAssetId, // First pair's asset ID
  currentPair,    // Currently selected pair
  setCurrentPair, // Set current pair
  isReady         // Whether pairs are loaded
} = useNodeFlowPairs();

useNodeFlowState()

Get SDK configuration state.

const { 
  supportedChainIds, // Supported chain IDs from backend
  isConfigReady,     // Config loaded
  apiUrl,            // Current API URL
  targetNetwork      // Current network
} = useNodeFlowState();

Using NodeFlowConfig (Existing Wagmi Setup)

If you already have Wagmi configured in your app, use NodeFlowConfig instead:

import { NodeFlowConfig, NodeFlowModal } from '@lnfi-network/nodeflow-sdk';

// Inside your existing WagmiProvider
<NodeFlowConfig apiUrl="<API_BASE_URL>">
  <NodeFlowModal />
  <YourApp />
</NodeFlowConfig>

License

MIT