npm package: @lnfi-network/astra-sdk
Description: [English](#english-documentation) | [简体中文](#中文文档)
Latest version: 1.0.1

# Astra SDK

[English](#english-documentation) | [简体中文](#中文文档)

<span id="english-documentation"></span>

## English Documentation

Astra SDK is a powerful React library that enables seamless asset bridging between EVM-compatible blockchains and the Bitcoin Lightning Network. Built with modern web technologies, it provides developers with an easy-to-integrate solution for cross-chain liquidity and payments.

### ✨ Features

- **Cross-Chain Bridge**: Bridge assets between EVM chains and Lightning Network.
- **Multi-Chain Support**: Support for Ethereum, Base, BSC, Botanix testnet, and more.
- **Wallet Integration**: Built-in support for WalletConnect and popular Web3 wallets.
- **TypeScript Ready**: Full TypeScript support with type definitions.
- **Responsive Design**: Mobile-first design with responsive UI components.
- **Real-time Updates**: Live transaction status and balance updates.
- **Customizable Theme**: Dark theme with customizable styling.

### � Workflows

#### 1. Lightning to EVM (Withdraw)
Used when a user sends BTC via Lightning to receive tokens on an EVM chain.

```mermaid
sequenceDiagram
    participant U as User / App
    participant S as Astra SDK
    participant L as LSP Node
    participant E as EVM Chain
    
    U->>S: astraSend(amount, assetId)
    S->>L: Request Quote & Astra Invoice
    L-->>S: Return LN Invoice
    S->>U: Display Invoice to User
    U->>L: User pays via Lightning Wallet
    L->>E: Trigger Smart Contract Release
    E-->>U: Mint/Transfer Tokens to User
```

#### 2. EVM to Lightning (Deposit)
Used when a user pays with EVM tokens to receive BTC on a Lightning Invoice.

```mermaid
sequenceDiagram
    participant U as User / App
    participant S as Astra SDK
    participant E as EVM Chain
    participant L as LSP Node
    
    U->>S: astraReceive(invoice, assetId)
    S-->>U: Show detailed quote
    U->>E: Approve & Deposit Tokens
    E-->>L: Lock assets in Contract
    L->>U: Pay User's Lightning Invoice
```

### �🚀 Quick Start

#### Installation

Astra SDK requires several peer dependencies to be installed in your project:

```bash
npm install @lnfi-network/astra-sdk wagmi viem @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
```

#### Basic Usage

```jsx
import React from 'react';
import { AstraProvider, AstraModal, astraSend, astraReceive } from '@lnfi-network/astra-sdk';

function App() {
  return (
    <AstraProvider 
      projectId="YOUR_WALLET_CONNECT_PROJECT_ID" 
      env="production" // 'production' or 'development'
    >
      <AstraModal />
      
      {/* Lightning to EVM */}
      <button onClick={() => astraSend({
        assetId: "your-asset-id",
        amount: 1000,
        waitConfirm: true,
        onAstraInvoice: (invoice, tx, txUrl) => {
          console.log("Astra Invoice Generated:", invoice);
        }
      })}>
        Bridge from Lightning
      </button>
      
      {/* EVM to Lightning */}
      <button onClick={() => astraReceive({
        assetId: "your-asset-id",
        invoice: "lnbc..." // Your receiving lightning invoice
      })}>
        Bridge to Lightning
      </button>
    </AstraProvider>
  );
}
```

### 📖 API Reference

#### AstraProvider

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `projectId` | `string` | **Required** | WalletConnect project ID from [cloud.reown.com](https://cloud.reown.com) |
| `env` | `'production' \| 'development'` | `'production'` | Environment mode. 'development' uses testnets (Sepolia, Base Sepolia) |
| `metadata` | `object` | `defaultMetadata` | App metadata for WalletConnect (name, description, url, icons) |
| `apiUrl` | `string` | See note | Backend API URL. Automatically switches based on `env` |
| `adapter` | `WagmiAdapter` | `null` | Optional custom Wagmi adapter if you want to reuse existing configuration |

#### astraSend

Bridge assets from **Lightning Network to EVM** chains.

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `assetId` | `string` | The ID of the asset to bridge |
| `amount` | `number` | Amount in satoshis |
| `waitConfirm` | `boolean` | Whether to wait for transaction confirmation (default: `true`) |
| `onAstraInvoice` | `function` | Callback: `(invoice, tx, txUrl) => void` |

#### astraReceive

Bridge assets from **EVM chains to Lightning Network**.

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `assetId` | `string` | The ID of the asset to bridge |
| `invoice` | `string` | The Lightning Network invoice where you want to receive funds |

---

<span id="中文文档"></span>

## 中文文档

Astra SDK 是一个强大的 React 库，旨在实现 EVM 兼容区块链与比特币闪电网络（Lightning Network）之间的无缝资产跨链转换。

### ✨ 功能特性

- **跨链桥接**：在 EVM 链和闪电网络之间进行资产转换。
- **多链支持**：支持 Ethereum, Base, BSC, Botanix 测试网等。
- **钱包集成**：内置对 WalletConnect 和主流 Web3 钱包的支持。
- **响应式设计**：移动端优先的设计，适配各种屏幕尺寸。
- **实时状态**：交易状态和余额的实时监控与更新。
- **隔离样式**：使用 `astra` 样式前缀，避免与宿主项目样式冲突。

### 🔄 业务流程

#### 1. 闪电网络 转 EVM (提现)
场景：用户支付闪电网络 Sats，在 EVM 链上接收对应的代币。

```mermaid
sequenceDiagram
    participant U as 用户 / 应用
    participant S as Astra SDK
    participant L as LSP 节点
    participant E as EVM 区块链
    
    U->>S: astraSend(金额, 资产ID)
    S->>L: 请求报价并生成 Astra 发票
    L-->>S: 返回生成的闪电网络发票
    S->>U: 引导用户使用钱包支付
    U->>L: 用户支付发票
    L->>E: 触发智能合约脚本
    E-->>U: 将代币转入用户 EVM 钱包
```

#### 2. EVM 转 闪电网络 (充值)
场景：用户在 EVM 链上支付代币，接收闪电网络上的比特币。

```mermaid
sequenceDiagram
    participant U as 用户 / 应用
    participant S as Astra SDK
    participant E as EVM 区块链
    participant L as LSP 节点
    
    U->>S: astraReceive(发票, 资产ID)
    S-->>U: 显示转换详情及报价
    U->>E: 授权并调用合约进行支付
    E-->>L: 合约锁定资产
    L->>U: 向用户的闪电网络发票付款
```

### 🚀 快速上手

#### 安装

Astra SDK 需要以下 peer dependencies 配合使用：

```bash
npm install @lnfi-network/astra-sdk wagmi viem @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
```

#### 基础用法

```jsx
import React from 'react';
import { AstraProvider, AstraModal, astraSend, astraReceive } from '@lnfi-network/astra-sdk';

function App() {
  return (
    <AstraProvider 
      projectId="YOUR_WALLET_CONNECT_PROJECT_ID" 
      env="production" // 'production' (正式网) 或 'development' (测试网)
    >
      <AstraModal />
      
      {/* 闪电网络 转 EVM (提现) */}
      <button onClick={() => astraSend({
        assetId: "your-asset-id",
        amount: 1000,
        onAstraInvoice: (invoice, tx, txUrl) => {
          console.log("生成的 Astra 发票:", invoice);
        }
      })}>
        从闪电网络桥接
      </button>
      
      {/* EVM 转 闪电网络 (充值) */}
      <button onClick={() => astraReceive({
        assetId: "your-asset-id",
        invoice: "lnbc..." // 你的闪电网络收款发票
      })}>
        桥接到闪电网络
      </button>
    </AstraProvider>
  );
}
```

### 📖 API 参考

#### AstraProvider (配置项)

| 属性 | 类型 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- |
| `projectId` | `string` | **必填** | 从 [cloud.reown.com](https://cloud.reown.com) 申请的 WalletConnect 项目 ID |
| `env` | `'production' \| 'development'` | `'production'` | 运行环境。'development' 会切换到测试网（Sepolia, Base Sepolia） |
| `metadata` | `object` | `defaultMetadata` | 在钱包中展示的应用信息（名称、描述、URL、图标） |
| `apiUrl` | `string` | 自动配置 | 后端 API 地址。通常根据 `env` 自动切换 |

#### astraSend

从 **闪电网络 (Lightning Network) 跨链到 EVM** 链。

| 参数 | 类型 | 描述 |
| :--- | :--- | :--- |
| `assetId` | `string` | 资产 ID |
| `amount` | `number` | 转换金额（单位：Sats） |
| `waitConfirm` | `boolean` | 是否等待交易确认 (默认: `true`) |
| `onAstraInvoice` | `function` | 回调函数: `(invoice, tx, txUrl) => void` |

#### astraReceive

从 **EVM 链跨链到 闪电网络 (Lightning Network)**。

| 参数 | 类型 | 描述 |
| :--- | :--- | :--- |
| `assetId` | `string` | 资产 ID |
| `invoice` | `string` | 你用于接收资金的闪电网络发票 |

---

## 🛠️ 技术栈

- **React 18** - UI 库
- **Wagmi & Viem** - 以太坊交互
- **Reown AppKit** - 钱包连接
- **Ant Design** - UI 组件 (使用 `astra` 前缀)
- **Zustand** - 状态管理

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件。

---

## 🔄 更新日志

### v1.0.1
- 正式版发布
- 修复了包名识别问题
- 完善了环境变量配置（Support for `env`, `apiUrl`）
- 增加了 `astraSend` 回调函数的详细参数声明

---

Built with ❤️ by the Astra Labs team