npm package: @nodeflow-network/nodeflow-sdk
Description: NodeFlow SDK is a React library that enables seamless asset bridging between EVM chains and the Bitcoin Lightning Network.
Latest version: 1.0.0

# 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 @nodeflow-network/nodeflow-sdk
# or
npm install @nodeflow-network/nodeflow-sdk
```

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

## Configuration

| Item | Value | Description |
| :--- | :--- | :--- |
| **Project ID** | Get from [WalletConnect](https://cloud.walletconnect.com/) | Required for wallet connection |
| **Dev API URL** | `<API_BASE_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 '@nodeflow-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'`

```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),
});
```

---

### Hooks

#### `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 '@nodeflow-network/nodeflow-sdk';

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

---

## License

MIT