# @canton-network/dapp-sdk 中文文档

规范地址：https://npmcn.com/package/%40canton-network/dapp-sdk/

版本：1\.9\.0
npm 元数据更新时间：2026-11-05T21:18:16.522Z
中文译文更新时间：2026-11-09T01:29:19.461Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40canton-network/dapp-sdk
原文对照：https://npmcn.com/package/%40canton-network/dapp-sdk/?lang=original
项目主页：https://github.com/canton-network/wallet/tree/main/sdk/dapp-sdk#readme
源码仓库：https://github.com/canton-network/wallet

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：556 kB，45 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：@walletconnect/types ^2\.23\.8，@walletconnect/sign-client ^2\.23\.8
- 首次发布：2025-08-28T19:22:07.034Z
- 最新版本发布：2026-11-05T21:18:16.352Z
- 近 30 天下载量：22046（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 34 个）

## 中文简介

Canton Network上的 dApp 开发浏览器 SDK

## 安装

```sh
npm install @canton-network/dapp-sdk
```

也可以使用：`pnpm add @canton-network/dapp-sdk`、`yarn add @canton-network/dapp-sdk`、`bun add @canton-network/dapp-sdk`

## README

# dApp SDK (英语)

**`@canton-network/dapp-sdk`** - 用于在平台上建立分散化应用程序的SDK类型 [广州网](https://www.canton.network/)。将用户连接到Canton钱包,管理账户,签名消息,以及执行交易——所有交易都通过一个供应商中立的接口,由 [CIP-0103 (中文(简体) )](https://github.com/canton-foundation/cips/blob/main/cip-0103/cip-0103.md)。 。 。 .

> \[注\] 每一份释放的移徙指南都公布于 [讨论情况](https://github.com/canton-network/wallet/discussions)。 。 。 .

## 特征

-   **钱包发现** 远程网关,EIP-6963型 `canton:announceProvider` 事件和可插接的适配器
-   **钱包拾取器 UI** – 内置,框架不可知的网络组件,允许用户选择钱包,输入自定义网关 URL,并管理最近使用的连接
-   **钱包连接** ——连接,断开,并监视连接状态
-   **账户管理** ——清单账户并应对账户变动
-   **交易执行** - 要求Daml交易的用户批准和签名
-   **编目 API 访问** - 代理认证向Canton JSON Ledger API提出的请求
-   **实时活动** 订阅状态变化、账户变化和交易生命周期事件
-   **多种运输** 用于远程钱包网关的HTTP/SSE, `postMessage` 浏览器扩展钱包
-   **提供者接口** - EIP-1193型CIP-103供应商通过 `getConnectedProvider()` 之后 `connect()`

## 安装

```shell
npm install @canton-network/dapp-sdk
```

```shell
pnpm add @canton-network/dapp-sdk
```

## 快速启动

最快的前进方式是通过模块级便利API. 它管理着一个单子 `DappClient` 在幕后,打开取钱包器,为您处理适配器注册.

```typescript
import * as sdk from '@canton-network/dapp-sdk'

// Opens the wallet picker and connects to the selected wallet
const result = await sdk.connect()
console.log(result.isConnected)

// List the user's accounts (parties)
const accounts = await sdk.listAccounts()

// Execute a transaction
await sdk.prepareExecute({
    commands: [
        {
            CreateCommand: {
                templateId: '#MyApp:MyModule:MyTemplate',
                createArguments: { owner: accounts[0].partyId },
            },
        },
    ],
})

// Listen for real-time updates
sdk.onTxChanged((tx) => {
    console.log('Transaction update:', tx)
})

// Disconnect when done
await sdk.disconnect()
```

## 建筑

SDK是围绕三层构建的:

```
┌──────────────────────────────────────────────┐
│  DappClient                                  │
│  Thin wrapper: typed RPC helpers, events,    │
│  session persist                             │
├──────────────────────────────────────────────┤
│  DiscoveryClient                             │
│  Adapter registry, session restore,          │
│  wallet picker integration                   │
├──────────────────────────────────────────────┤
│  ProviderAdapter implementations             │
│  ExtensionAdapter (announce protocol)        │
│  (browser / postMessage)                     │
│  RemoteAdapter (HTTP/SSE gateway)            │
└──────────────────────────────────────────────┘
```

## 钱包提供者

钱包和扩展作者:参见 **[钱包提供者(发现)](https://github.com/canton-network/wallet/blob/main/docs/dapp-sdk/wallet-providers/integration-overview.md)** 在dApp 大楼的文档中,说明如何在拾取器中出现(`RemoteAdapter`, (中文(简体) ), `canton:announceProvider`,以及 `additionalAdapters`) (中文(简体) ).

## 使用量

### 选项A:模块级API(推荐给大多数应用程序)

导入 SDK 作为命名空间 。 这个 `connect()` 函数打开内置的钱包拾取器、登记可用的适配器并返回 a `ConnectResult`。 。 。 .

```typescript
import * as sdk from '@canton-network/dapp-sdk'
import { RemoteAdapter } from '@canton-network/dapp-sdk'

await sdk.connect()
const status = await sdk.status()
```

您可以在连接时间提供额外的适配器 :

```typescript
await sdk.connect({
    additionalAdapters: [
        new RemoteAdapter({
            name: 'My Gateway',
            rpcUrl: 'https://gateway.example.com/api/json-rpc',
        }),
    ],
})
```

### 备选案文B:与发现对象的匹配

要对适配器注册和连接流程进行更多的控制,请使用 `DiscoveryClient` 直接传递给生成的提供者 `DappClient`。 。 。 .

```typescript
import {
    DappClient,
    DiscoveryClient,
    RemoteAdapter,
} from '@canton-network/dapp-sdk'

const discovery = await DiscoveryClient.create({
    adapters: [
        new RemoteAdapter({
            name: 'Splice Wallet Gateway',
            rpcUrl: 'https://gateway.example.com/api/json-rpc',
        }),
    ],
})
await discovery.connect() // opens the picker if configured

const session = discovery.getActiveSession()!
const client = new DappClient(session.provider, {
    providerType: session.adapter.type,
})

const status = await client.status()
```

### 备选案文C:与供应商直接兼容

如果你已经有一个 `Provider<DappRpcTypes>` (例如从自己的适配器),你可以完全跳过发现.

```typescript
import { DappClient, RemoteAdapter } from '@canton-network/dapp-sdk'

const provider = new RemoteAdapter({
    name: 'Splice Wallet Gateway',
    rpcUrl: 'https://gateway.example.com/api/json-rpc',
}).provider()

const client = new DappClient(provider)
const result = await client.connect()
```

## API 参考

### 达标

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `connect()` | `ConnectResult` | 通过提供者启动连接 |
| `disconnect()` | `void` | 断开连接并清除本地状态 |
| `status()` | `StatusEvent` | 当前连接状态 |
| `listAccounts()` | `ListAccountsResult` | 列出用户账户( 当事方) |
| `prepareExecute(params)` | `null` | 提交交易供签署 |
| `prepareExecuteAndWait(params)` | `PrepareExecuteAndWaitResult` | 提交并等待完成 |
| `ledgerApi(params)` | `LedgerApiResult` | 代理编辑器 API 请求 |
| `open()` | `void` | 打开钱包 UI |
| `getProvider()` | `Provider` | 访问基本提供者 |
| `onStatusChanged(listener)` | `void` | 订阅状态更改 |
| `onAccountsChanged(listener)` | `void` | 订阅到账户更改 |
| `onTxChanged(listener)` | `void` | 订阅交易更改 |

### Dapplient 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `providerType` | `ProviderType` | `'remote'` | 感染 `open()` 路线(`'browser'` 使用后Message, 其他人使用弹出) |

### 发现对象

| 方法 | 说明 |
| --- | --- |
| `create(config)` | 创建初始化客户端并尝试恢复会话 |
| `registerAdapter(adapter)` | 添加一个 `ProviderAdapter` 运行时间 |
| `listAdapters()` | 列出已注册适配器 |
| `connect(providerId?)` | 连接到特定的适配器或打开取取器 |
| `disconnect()` | 断开活动会话 |
| `getActiveSession()` | 获取当前 `ActiveSession` 或者说 `null` |
| `on(event, handler)` | 听着 `discovery:connected`, (中文(简体) ), `discovery:disconnected`, (中文(简体) ), `discovery:error` |
| `removeListener(event, handler)` | 删除事件倾听器 |

### 内建适应器

| 适配器 | 提供者类型 | 运输 | 说明 |
| --- | --- | --- | --- |
| `ExtensionAdapter` | `'browser'` | `postMessage` | 浏览器扩展通过 `canton:announceProvider` (单位:千美元)[钱包提供者指南](https://github.com/canton-network/wallet/blob/main/docs/dapp-sdk/wallet-providers/integration-overview.md)) (中文(简体) ). |
| `RemoteAdapter` | `'remote'` | HTTP/SSE 软件 | CIP-103 钱包 网络上的网关. |

## 文档

完整的文档,包括详细的使用指南,API参考,以及钱包网关的配置:

-   [dApp 建筑指南](https://github.com/canton-network/wallet/tree/main/docs/dapp-building)
-   [dApp SDK 文档](https://github.com/canton-network/wallet/tree/main/docs/dapp-sdk)
-   [钱包提供者(发现)](https://github.com/canton-network/wallet/blob/main/docs/dapp-sdk/wallet-providers/integration-overview.md)
-   [API 规格(开放RPC)](https://github.com/canton-network/wallet/tree/main/api-specs)
-   [示例 dApps](https://github.com/canton-network/wallet/tree/main/examples)

## 许可证

[阿帕奇 - 2.0](https://github.com/canton-network/wallet/blob/main/LICENSE)

## 常见问题

### @canton-network/dapp-sdk 是什么？

Canton Network上的 dApp 开发浏览器 SDK

### 如何安装 @canton-network/dapp-sdk？

在项目目录运行 npm install @canton-network/dapp-sdk，或使用 pnpm add / yarn add / bun add。

### @canton-network/dapp-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @canton-network/dapp-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @canton-network/dapp-sdk 可以商用吗？

@canton-network/dapp-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @canton-network/dapp-sdk 的下载量有多少？

根据 npm 官方下载统计，@canton-network/dapp-sdk 在 2026/10/09 – 2026/11/07 这 30 天内被下载 22,046 次，日均约 735 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @canton-network/dapp-sdk 还在维护吗？

最新版本 1\.9\.0 发布于 2026/11/06（3 天前）；至今共发布 49 个版本，其中过去 12 个月发布了 34 个；首次发布于 2025/08/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。