@lnfi-network/nodeflow-sdk 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,276 @@
+# 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
+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](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 '@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'`
+
+```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 '@lnfi-network/nodeflow-sdk';
+
+// Inside your existing WagmiProvider
+<NodeFlowConfig apiUrl="<API_BASE_URL>">
+  <NodeFlowModal />
+  <YourApp />
+</NodeFlowConfig>
+```
+
+---
+
+## License
+
+MIT