nexus-sdk-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nexus SDK Setup

Nexus SDK 安装配置

Install dependency

安装依赖

Install the SDK package:

```
npm install @avail-project/nexus-core
```
or
```
pnpm add @avail-project/nexus-core
```
or
```
yarn add @avail-project/nexus-core
```

安装SDK包：

```
npm install @avail-project/nexus-core
```
或
```
pnpm add @avail-project/nexus-core
```
或
```
yarn add @avail-project/nexus-core
```

Obtain an EIP-1193 provider

获取EIP-1193 provider

Use any wallet connection stack to get a provider.
Ensure the provider has a
```
request
```
method.
Use a browser fallback only when appropriate:
- ```
const provider = (window as any).ethereum
```

使用任意钱包连接栈获取provider。
确保provider具备
```
request
```
方法。
仅在合适场景下使用浏览器兜底方案：
- ```
const provider = (window as any).ethereum
```

Construct the SDK instance

构建SDK实例

Create

new NexusSDK({ network, debug, siweChain })

Provide
```
network
```
:
- ```
'mainnet'
```
  or
```
'testnet'
```
  to use default endpoints.
- ```
NetworkConfig
```
  to use custom endpoints.
Provide
```
debug?: boolean
```
to enable verbose SDK logging.
Provide
```
siweChain?: number
```
to set the SIWE chain id (if you use SIWE).

创建

new NexusSDK({ network, debug, siweChain })

。

传入
```
network
```
参数：
- 传入
```
'mainnet'
```
  或
```
'testnet'
```
  使用默认端点。
- 传入
```
NetworkConfig
```
  使用自定义端点。
可选传入
```
debug?: boolean
```
开启SDK详细日志。
可选传入
```
siweChain?: number
```
设置SIWE链ID（如果你使用SIWE的话）。

Initialize once

单次初始化

Create a single instance and reuse it.
Store the instance in a module singleton or a React ref.
Guard with
```
sdk.isInitialized()
```
to avoid re-init.

创建单个实例并复用。
将实例存储在模块单例或React ref中。
使用
```
sdk.isInitialized()
```
做守卫避免重复初始化。

Minimal example

最简示例

import { NexusSDK, type EthereumProvider } from '@avail-project/nexus-core';

const sdk = new NexusSDK({ network: 'mainnet' });

export async function initNexus(provider: EthereumProvider) {
  if (sdk.isInitialized()) return sdk;
  if (!provider || typeof provider.request !== 'function') {
    throw new Error('Invalid EIP-1193 provider');
  }
  await sdk.initialize(provider);
  return sdk;
}

import { NexusSDK, type EthereumProvider } from '@avail-project/nexus-core';

const sdk = new NexusSDK({ network: 'mainnet' });

export async function initNexus(provider: EthereumProvider) {
  if (sdk.isInitialized()) return sdk;
  if (!provider || typeof provider.request !== 'function') {
    throw new Error('Invalid EIP-1193 provider');
  }
  await sdk.initialize(provider);
  return sdk;
}

Initialize when a wallet kit is already integrated (FamilyKit / wagmi-based)

已集成钱包套件（基于FamilyKit / wagmi）时的初始化方式

If your kit exposes a wagmi connector, derive an EIP-1193 provider from it.
Use the same pattern as Nexus Elements: prefer
```
connector.getProvider()
```
on desktop and a
```
walletClient.request
```
wrapper on mobile.
Example (adapt to your hooks and UI state):

import { NexusSDK, type EthereumProvider } from '@avail-project/nexus-core';
import { useAccount, useConnectorClient } from 'wagmi';

const sdk = new NexusSDK({ network: 'mainnet', debug: false });

async function initFromWalletKit(isMobile: boolean) {
  const { connector } = useAccount();
  const { data: walletClient } = useConnectorClient();

  const mobileProvider =
    walletClient &&
    ({
      request: (args: unknown) => walletClient.request(args as never),
    } as EthereumProvider);

  const desktopProvider = await connector?.getProvider();
  const effectiveProvider = isMobile ? mobileProvider : desktopProvider;

  if (!effectiveProvider || typeof effectiveProvider.request !== 'function') {
    throw new Error('Invalid EIP-1193 provider from wallet kit');
  }

  if (!sdk.isInitialized()) {
    await sdk.initialize(effectiveProvider);
  }

  return sdk;
}

如果你的套件暴露了wagmi连接器，可以从中派生EIP-1193 provider。
遵循Nexus Elements的相同模式：桌面端优先使用
```
connector.getProvider()
```
，移动端使用
```
walletClient.request
```
封装。
示例（适配你自己的hooks和UI状态）：

import { NexusSDK, type EthereumProvider } from '@avail-project/nexus-core';
import { useAccount, useConnectorClient } from 'wagmi';

const sdk = new NexusSDK({ network: 'mainnet', debug: false });

async function initFromWalletKit(isMobile: boolean) {
  const { connector } = useAccount();
  const { data: walletClient } = useConnectorClient();

  const mobileProvider =
    walletClient &&
    ({
      request: (args: unknown) => walletClient.request(args as never),
    } as EthereumProvider);

  const desktopProvider = await connector?.getProvider();
  const effectiveProvider = isMobile ? mobileProvider : desktopProvider;

  if (!effectiveProvider || typeof effectiveProvider.request !== 'function') {
    throw new Error('Invalid EIP-1193 provider from wallet kit');
  }

  if (!sdk.isInitialized()) {
    await sdk.initialize(effectiveProvider);
  }

  return sdk;
}

Handle disconnect / teardown

处理断开连接/销毁

On wallet disconnect, call
```
await sdk.deinit()
```
.
Clear state (balances, hook refs, cached intents).

钱包断开连接时，调用
```
await sdk.deinit()
```
。
清除状态（余额、hook引用、缓存的意图）。

Use provider-only mode (optional)

仅provider模式（可选）

If you need balances before full init, call:
- ```
await sdk.setEVMProvider(provider)
```
Check
```
sdk.hasEvmProvider
```
to confirm.

如果你需要在完全初始化前获取余额，调用：
- ```
await sdk.setEVMProvider(provider)
```
检查
```
sdk.hasEvmProvider
```
确认配置成功。

Handle SSR / client-only execution

处理SSR / 仅客户端执行

Initialize in client-only code (
```
useEffect
```
or dynamic import) to avoid SSR issues.

在仅客户端代码中初始化（
```
useEffect
```
或动态导入）避免SSR问题。

Handle account changes

处理账户变更

If provider supports events, re-fetch balances on
```
accountsChanged
```
.
If provider lacks
```
.on
```
/
```
.removeListener
```
, call:
- ```
sdk.triggerAccountChange()
```
  after the wallet address changes.

如果provider支持事件，在
```
accountsChanged
```
事件触发时重新获取余额。
如果provider没有
```
.on
```
/
```
.removeListener
```
方法，在钱包地址变更后调用：
- ```
sdk.triggerAccountChange()
```

Handle init errors

处理初始化错误

Wrap
```
sdk.initialize
```
in try/catch.

SDK_INIT_STATE_NOT_EXPECTED

, call

await sdk.deinit()

and retry.

WALLET_NOT_CONNECTED

CONNECT_ACCOUNT_FAILED

, prompt user to reconnect.

用try/catch包裹
```
sdk.initialize
```
调用。

如果返回

SDK_INIT_STATE_NOT_EXPECTED

，调用

await sdk.deinit()

后重试。

如果返回
```
WALLET_NOT_CONNECTED
```
或
```
CONNECT_ACCOUNT_FAILED
```
，提示用户重新连接。