# `@okxconnect/connect-kit`

中文 / [英文](./README.md)

OKX Web3 Connect Kit 是一个轻量级 SDK，旨在帮助开发者快速集成 OKX Connect，覆盖多个生态系统，包括 **Web**、**移动端** 和 **Telegram**。它支持主流区块链标准，例如 **EIP-6963** 和 **wallet-standard**，提供 **钱包 Provider 注入和检测** 功能，实现 DApp 无缝集成，极大地减少开发和集成成本。现有 DApp 通常只需两行代码即可快速完成适配。

```bash
npm i @okxconnect/connect-kit
```

## DApp 使用场景

根据您的 DApp 场景选择适配方案。现有 DApp 可快速集成功能，而新 DApp 可参考下方完整的 **集成示例** 和 **API 文档**。

### 1. 在 Telegram 或移动端浏览器中

在移动端浏览器和 Telegram 场景中，Connect Kit 会自动注入 Ethereum 和 Solana 等链的 Provider，并广播 **EIP-6963** 和 **wallet-standard** 事件，无需额外代码更改。

**现有Dapp快速接入**

```javascript
import { init } from '@okxconnect/connect-kit';
await init();
```

**新Dapp接入**

```javascript
// 步骤 1：初始化
import { init } from '@okxconnect/connect-kit';
await init();

// 步骤 2：添加事件
window.ethereum.on('connect', (result) => {
  console.log('chainId: ', result.chainId);
});
window.ethereum.on('accountsChanged', (result) => {
  console.log('address: ', result[0]);
});

// 步骤 3：连接
// 选项 1：使用 window.ethereum 连接
const result = await window.ethereum.request({ method: 'eth_requestAccounts' });
console.log('address: ', result[0]);

// 选项 2：连接到 OKX Mini Wallet
import { connectOKXMiniWallet } from '@okxconnect/connect-kit';
connectOKXMiniWallet();

// 选项 3：连接到 OKX App Wallet
import { connectOKXAppWallet } from '@okxconnect/connect-kit';
connectOKXAppWallet();
```

### 2. 在 PC 浏览器中

在 **PC 环境** 中，在Connect Kit自动注入外还可选择手动切换Provider

- 对于支持 **EIP-6963** 或 **wallet-standard** 的 DApp，仅需init即可。
- 对于不支持这些标准或需集成多个钱包的 DApp，可通过 [setProvider](https://docs.web3js.org/libdocs/AccountAbstraction#setprovider) 方法手动切换 Provider。

**现有Dapp快速接入（支持6963 或 wallet standard）**

```javascript
// 初始化
import { init } from '@okxconnect/connect-kit';
await init();
```

**现有Dapp快速接入（不支持 6963 或 Wallet Standard）**

> 支持切换 Provider

```javascript
// 步骤 1：初始化
import { init } from '@okxconnect/connect-kit';
await init();

// 步骤 2：获取 Provider
import { getProvider, SupportedNetworks } from '@okxconnect/connect-kit';
const provider = getProvider(SupportedNetworks.ETHEREUM);

// setProvider 的实现可参考 [web3.js](https://docs.web3js.org/libdocs/AccountAbstraction#setprovider)
setProvider(provider);
```

**新Dapp接入完整示例，支持6963**

```javascript
// 步骤 1：初始化
import { init } from '@okxconnect/connect-kit';
await init();

// 步骤 2：获取 Provider
window.addEventListener('eip6963:announceProvider', (event) => {
  setProvider(event.detail.provider);
  console.log('provider:', event.detail.provider);
});

// 步骤 3：使用 Provider 连接
const result = await provider.request({ method: 'eth_requestAccounts' });
console.log('address: ', result[0]);
```

**新Dapp接入完整示例，不支持6963**

```javascript
// 步骤 1：初始化
import { init, getProvider, SupportedNetworks } from '@okxconnect/connect-kit';
await init();

// 步骤 2：获取 Provider
const provider = getProvider(SupportedNetworks.ETHEREUM);
setProvider(provider);

// 步骤 3：添加 Ethereum 事件
provider.on('connect', function(result){
  console.log('chainId: ', result.chainId)
});
provider.on('accountsChanged', function(result){
  console.log('address: ', result[0]);
});

// 步骤 4：连接
// 选项 1：使用 window.ethereum 连接
const result = await window.ethereum.request({ method: 'eth_requestAccounts' });
console.log('address: ', result[0]);

// 选项 2：连接到 OKX Mini Wallet
import { connectOKXMiniWallet } from '@okxconnect/connect-kit';
connectOKXMiniWallet();

// 选项 3：连接到 OKX App Wallet
import { connectOKXAppWallet } from '@okxconnect/connect-kit';
connectOKXAppWallet();
```

### 3. 扫描二维码连接

```javascript
import { getConnectKit, getUri } from '@okxconnect/connect-kit';

// 订阅二维码事件
const connectKit = getConnectKit();

connectKit.once('session_connecting', () => {
  console.log('session_connecting, QR Code');
});
connectKit.once('connect', () => {
  console.log('Connected');
});
connectKit.once('connect_error', () => {
  console.log('Connection error');
});

const uri = await getUri();
console.log('显示二维码扫描链接: ', uri);
```

**React 示例**

```javascript
import { useState } from 'react';
import { getConnectKit, getUri } from '@okxconnect/connect-kit';

const [connecting, setConnecting] = useState(false);
const [uri, setUri] = useState('');
const getUriForQrCode = async () => {
  const connectKit = getConnectKit();

  connectKit.once('session_connecting', () => {
    setConnecting(true);
    console.log('session_connecting, QR Code');
  });
  connectKit.once('connect', () => {
    setConnecting(false);
    console.log('Connected');
  });
  connectKit.once('connect_error', () => {
    setConnecting(false);
    console.log('Connection error');
  });

  const newUri = await getUri();
  setUri(newUri);
  console.log('显示二维码扫描链接: ', uri);
};

<button onClick={getUriForQrCode}>获取二维码</button>;
```

### API

```javascript
import { xxx } from '@okxconnect/connect-kit';
```

| 方法                     | 返回类型            | 描述                                               |
| ------------------------ | ------------------- | -------------------------------------------------- |
| `async init(config)`     | `ConnectKit object` | 初始化 Provider，并与 OKX Connect 服务器建立连接。 |
| `async getUri()`         | `uri`               | 获取 App Wallet 或 Mini Wallet 的二维码链接。      |
| `connectOKXAppWallet()`  | `void`              | 直接连接 App Wallet，适用于移动端网页或 Telegram。 |
| `connectOKXMiniWallet()` | `void`              | 直接连接 Mini Wallet，适用于 PC 和移动端环境。     |
| `getProvider(network)`   | `provider`          | 返回指定网络的钱包 Provider。                      |
| `disconnect()`           | `void`              | 断开钱包连接。                                     |

### 支持的网络

| 枚举     | 值         | 描述              | 状态   |
| -------- | ---------- | ----------------- | ------ |
| ETHEREUM | `ethereum` | EVM 兼容的网络    | 已完成 |
| SOLANA   | `solana`   | Solana 兼容的网络 | 已完成 |
| APTOS    | `aptos`    | Aptos 网络        | 已完成 |
| BITCOIN  | `bitcoin`  | 比特币兼容的网络  | 已完成 |
| TON      | `ton`      | TON 网络          | 已完成 |
| SUI      | `sui`      | SUI 网络          | 已完成 |
| COSMOS   | `cosmos`   | Cosmos 兼容的网络 | 开发中 |

### 错误码

符合 [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) 和 [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474) 标准。

| 枚举                     | 值       | 描述                            |
| ------------------------ | -------- | ------------------------------- |
| USER_REJECTS_ERROR       | `4001`   | 用户拒绝请求。                  |
| UNAUTHORIZED_ERROR       | `4100`   | 方法或账户未被用户授权。        |
| UNSUPPORTED_METHOD_ERROR | `4200`   | Provider 不支持该方法。         |
| DISCONNECTED_ERROR       | `4900`   | Provider 与区块链断开连接。     |
| CHAIN_DISCONNECTED_ERROR | `4901`   | Provider 未连接到请求的区块链。 |
| INTERNAL_ERROR           | `-32603` | 内部 JSON-RPC 错误。            |