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

``bash
yarn add @lnfi-network/nodeflow-sdk


or

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

---

Quick Start

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

function App() {
return (
projectId="your-walletconnect-project-id"
apiUrl=""
>



);
}

function MyBridgeUI() {
// Get available trading pairs dynamically - no hardcoded asset IDs needed!
const { pairs, defaultAssetId, isReady } = useNodeFlowPairs();

if (!isReady) return

`
┌─────────────────────────────────────────────────────────────────────────────┐
│ 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! │ │
◄──────────────────────────────│ │
`

$3

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

$3

####

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 |

####

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

---

$3

#### 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'

`javascript
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'

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

---

$3

#### useNodeFlowPairs()

Get available trading pairs for the current chain.

`javascript
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.

`javascript
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:

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

// Inside your existing WagmiProvider




``

---

License

MIT