# @circle-fin/adapter-solana-kit 中文文档

规范地址：https://npmcn.com/package/%40circle-fin/adapter-solana-kit/

版本：1\.7\.1
npm 元数据更新时间：2026-11-05T17:20:51.111Z
中文译文更新时间：2026-11-09T16:47:51.067Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40circle-fin/adapter-solana-kit
原文对照：https://npmcn.com/package/%40circle-fin/adapter-solana-kit/?lang=original

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

- 包体积（解压后）：4.9 MB，18 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：13 个
- peer 依赖：@solana/kit ^5\.0\.0，@solana/web3\.js ^1\.98\.2
- 首次发布：2025-11-11T16:57:15.446Z
- 最新版本发布：2026-11-05T17:20:50.874Z
- 近 30 天下载量：9814（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 34 个）

## 中文简介

索拉纳区块链适配器由@solana/kit供电

## 安装

```sh
npm install @circle-fin/adapter-solana-kit
```

也可以使用：`pnpm add @circle-fin/adapter-solana-kit`、`yarn add @circle-fin/adapter-solana-kit`、`bun add @circle-fin/adapter-solana-kit`

## README

# 索拉纳 Kit 适配器

[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

**@solana/kit提供索拉纳适应器执行动力**

_App Kits生态系统的索拉纳现代功能集成_

## 目录

-   [索拉纳 Kit 适配器](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-solana-kit-adapter)
    -   [目录](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-table-of-contents)
    -   [概览](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-overview)
        -   [为什么是索拉纳・克特・适配器?](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-why-solana-kit-adapter)
        -   [我何时该用索拉纳套装机?](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-when-and-how-should-i-use-the-solana-kit-adapter)
            -   [我是一个使用工具包的开发商](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-im-a-developer-using-a-kit)
                -   [示例](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-example)
            -   [我是一个开发商 制作一个 Kit 提供者](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-im-a-developer-making-a-kit-provider)
    -   [安装](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-installation)
        -   [同伴依赖关系](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-peer-dependencies)
        -   [解决同伴依赖的问题](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-troubleshooting-peer-dependencies)
            -   [缺少同伴依赖性警告](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-missing-peer-dependency-warning)
            -   [版本冲突](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-version-conflict)
            -   [在@solana/web3.js和@solana/kit之间选择](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-choosing-between-solanaweb3js-and-solanakit)
            -   [使用不兼容的版本](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-using-incompatible-versions)
    -   [快速启动](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-quick-start)
        -   [\* \* 采用工厂方法的简单设置(建议)](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme--easy-setup-with-factory-methods-recommended)
        -   [生产考虑](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme--production-considerations)
        -   [QQ 浏览器支持钱包提供者](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme--browser-support-with-wallet-providers)
        -   [高级手动设置](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme--advanced-manual-setup)
    -   [下一个Generation API(`/next`(中文(简体) )](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-next-generation-api-next)
        -   [开始 `/next`](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-getting-started-with-next)
        -   [为什么 `/next`? 吗?](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-why-next)
        -   [目前的限制 `/next`](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-current-limitations-of-next)
        -   [已编制交易:估计、模拟、执行](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-prepared-transactions-estimate-simulate-execute)
        -   [日志](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-logging)
        -   [计量](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-metrics)
        -   [托肯书记官处](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-token-registry)
        -   [交易调制](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-transaction-tuning)
        -   [迁移路径](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-migration-path)
    -   [特征](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-features)
    -   [用法实例](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-usage-examples)
        -   [工厂方法的基本使用](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-basic-usage-with-factory-methods)
        -   [多密钥格式支持](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-multiple-private-key-format-support)
        -   [横琴桥(EVM-索拉纳)](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-cross-chain-bridge-evm--solana)
        -   [浏览器钱包集成](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-browser-wallet-integration)
        -   [用 @ solana/ kit 客户端进行手动设置](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-manual-setup-with-solanakit-clients)
    -   [支持的网络](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-supported-networks)
    -   [API 参考](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-api-reference)
        -   [工厂方法](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-factory-methods)
            -   [`createSolanaKitAdapterFromPrivateKey(options)`](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-createsolanakitadapterfromprivatekeyoptions)
            -   [`createSolanaKitAdapterFromProvider(options)`](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-createsolanakitadapterfromprovideroptions)
        -   [构造选项](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-constructor-options)
        -   [方法](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-methods)
        -   [额外出口](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-additional-exports)
    -   [建筑](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-architecture)
        -   [与 @ solana/web3.js 的密钥差异](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-key-differences-from-solanaweb3js)
        -   [@solana/kit架构的好处](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-benefits-of-solanakit-architecture)
        -   [交易楼模式](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-transaction-building-pattern)
    -   [与 App Kit 整合](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-integration-with-app-kit)
    -   [发展](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-development)
    -   [许可证](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-license)

## 概览

Solana Kit适配器是执行《公约》的有力类型 `Adapter` 接口 **索拉纳区块链**. 建于现代之上 [@ solana/ kit (英语)](https://www.npmjs.com/package/@solana/kit) 库(successor to @solana/web3.js),它通过一个统一接口提供类型安全、功能性的块链交互,设计与该接口无缝工作 [桥套](https://www.npmjs.com/package/@circle-fin/bridge-kit) 用于索拉纳网络和EVM网络之间跨链的USDC转移,以及用于额外稳定币业务的任何未来工具包.

### 为什么是索拉纳・克特・适配器?

-   **@ @ solana/ kit 集成**: 采用现代可变树型建造 [@ solana/ kit (英语)](https://www.npmjs.com/package/@solana/kit) 图书馆
-   **{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}对面准备**: 为与BridgeKit生态系统无缝结合而设计
-   **QQ 类型安全**: 完整类型脚本支持, 严格类型检查
-   **函数 API**@solana/kit的功能交易构建模式
-   **++ 多个签名人**: 支持私人密钥和钱包提供者签名器
-   **\### 有树摇动**: 优化捆绑大小并有选择地进口
-   **行动系统**: 代号操作和CCTP综合操作处理器

### 我何时该用索拉纳套装机?

#### 我是一个使用工具包的开发商

如果你用其中一个工具箱来做一些动作,例如从链"A"到链"B"的连接,那么你只需要将适配器切换为你的链并传递到工具箱.

##### 示例

```typescript
const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
})
```

_见 [快速启动](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-quick-start) 关于如何使用Solana Kit适配器的更深入的指南._

#### 我是一个开发商 制作一个 Kit 提供者

如果您正在制作一个供其他 Kit 用户插入套件的提供者, 例如 a `BridgingProvider`,你需要与不同的链子互动, 然后,你需要使用抽象的 `Adapter` 在链上执行的方法.

## 安装

```bash
npm install @circle-fin/adapter-solana-kit @solana/kit @solana/web3.js
# or
yarn add @circle-fin/adapter-solana-kit @solana/kit @solana/web3.js
```

### 同伴依赖关系

这个适配器需要 `@solana/kit` 财务报告和审定财务报表 `@solana/web3.js` 作为对等依赖,允许您自己管理版本并避免与您现有的依赖冲突.

**必要的同伴依赖性 :**

-   `@solana/kit`数字 : `^5.0.0` (支持@solana/kit 5.0.0至 5.x.x,不包括 6.x.x)
-   `@solana/web3.js`数字 : `^1.98.2` (支持@solana/web3.js 1.98.2至 1.x.x,不包括 2.x.x)

**安装 :**

```bash
# Install the adapter and all peer dependencies
npm install @circle-fin/adapter-solana-kit @solana/kit @solana/web3.js

# Or with yarn
yarn add @circle-fin/adapter-solana-kit @solana/kit @solana/web3.js
```

**版本兼容性 :**

| 软件包 | 范围 | 含义 |
| --- | --- | --- |
| `@solana/kit` | `^5.0.0` | ✅ 5.0.0至 5.x.x  
6.x.x及以上(突破性变化) |
| `@solana/web3.js` | `^1.98.2` | 1.98.2至1.x.x  
2.x.x及以上(突破性变化) |

**同伴依赖的好处:**

-   **减少捆绑大小**:避免重复安装索拉纳图书馆
-   **版本控制**: 使用最适合您项目的版本
-   **预防冲突**:适配器与您的代码之间没有版本不匹配
-   **灵活性**: 在需要时独立升级
-   **树摇**: @solana/kit的模块化架构从单一安装中受益

**说明:** 适配器使用 SPL Token 内置帮助器 `@core/adapter-solana-base` 避免拉入被腐烂的 `@solana/spl-token` b. 一揽子方案及其脆弱性 `bigint-buffer` 过渡性依赖(GHSA-3gc7-fjrx-p6mg). 列出的同级依赖关系(`@solana/kit` 财务报告和审定财务报表 `@solana/web3.js`)直接用于适配器的源代码.

### 解决同伴依赖的问题

#### 缺少同伴依赖性警告

如果您看到警告, 如:

```
npm WARN @circle-fin/adapter-solana-kit@x.x.x requires a peer of @solana/kit@^5.0.0 but none is installed.
npm WARN @circle-fin/adapter-solana-kit@x.x.x requires a peer of @solana/web3.js@^1.98.2 but none is installed.
```

**解决方案**: 在适配器旁安装所有对等依赖性 :

```bash
npm install @solana/kit @solana/web3.js
```

#### 版本冲突

如果您看到冲突版本的错误 :

```
npm ERR! Could not resolve dependency:
npm ERR! peer @solana/kit@"^5.0.0" from @circle-fin/adapter-solana-kit
npm ERR! peer @solana/web3.js@"^1.98.2" from @circle-fin/adapter-solana-kit
```

**解决方案**: 确保您的项目使用兼容的版本 :

```bash
# Check your current versions
npm list @solana/kit @solana/web3.js

# Update to compatible versions if needed
npm install @solana/kit@^5.0.0 @solana/web3.js@^1.98.2
```

#### 在@solana/web3.js和@solana/kit之间选择

如果你不确定哪个索拉纳适配器使用:

-   **使用 @ circle- fin/ adapter- solana- kit** 如果:
    
    -   您想要现代功能 API
    -   需要摇倒花花花花样
    -   你要开始一个新项目了
    -   您想要利用 @ solana/ kit 的模块架构
-   **使用 @ circle- fin/ adapter- solana 选项** 如果:
    
    -   您已经在您的工程中使用了 @ solana/ web3.js
    -   您需要与已有的 Web3.js 代码兼容
    -   你在迁移一个已有的项目

#### 使用不兼容的版本

如果您需要使用更新的主要版本,适配器可能无法正确工作:

**@solana/kit 6.x.x 或 @solana/web3.js 2.x.x:**

1.  **保留所支持的版本**: 使用所支持范围内的版本
    -   @solana/kit: 5.0.0 - 5.x.x
    -   @solana/web3.js: 1.98.2 - 1.x.x
2.  **检查更新**: 寻找支持更新库版本的更新适配器版本
3.  **报表兼容性**: 在 App Kits 存储器上打开一期

再来点帮助 拜访一下我们 [服务台](https://help.circle.com/s/submit-ticket) 或者说 [解析器](https://discord.com/invite/buildoncircle)。 。 。 .

## 快速启动

### \* \* 采用工厂方法的简单设置(建议)

最简单的开始方法是我们工厂的方法. **有可靠的默认 RPC 端点** - 不需要配置索拉纳RPC供应商!

```typescript
import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit'

// Create an adapter with built-in reliable RPC endpoints
const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!, // Base58, Base64, or JSON array format
})

// Ready to use with Stablecoin Kits!
const address = await adapter.getAddress()
console.log('Connected address:', address)
```

**关键特性**: 所有索拉纳链条包括使用 @solana/ kit 的可靠默认 RPC 端点 `createSolanaRpc()`。 。 。 .

### 生产考虑

> **对生产很重要**:工厂方法在不提供自定义的RPC时默认使用公共RPC端点,这可能会有率限制和较低的可靠性. 对于生产应用,我们强烈建议提供定制的RPC客户端.

```typescript
import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit'
import { createSolanaRpc } from '@solana/kit'

// Production-ready setup with custom RPC endpoints
const customRpc = createSolanaRpc(
  `https://solana-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
)

const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  getRpc: () => customRpc,
})
```

### QQ 浏览器支持钱包提供者

对于带有Phantom, Solflare 或 Backpack 等钱包提供者的浏览器环境:

```typescript
import { createSolanaKitAdapterFromProvider } from '@circle-fin/adapter-solana-kit'

// Create an adapter from a browser wallet
const adapter = await createSolanaKitAdapterFromProvider({
  provider: window.solana, // Phantom, Solflare, etc.
})
```

**执行情况**时间轴: **已完全执行**

-   ✅ **连接管理**: 完成 RPC 代理和签名抽象
-   ✅ **类型安全**齐全 `TransactionSigner` 与本地加密 API 接口
-   ✅ **处理错误**: 全面验证和描述性错误信息
-   ✅ **钱包整合**: 在 @ solana/ kit 和钱包标准之间完成交易格式转换

**建议**: 使用 `createSolanaKitAdapterFromPrivateKey()` 用于服务器侧应用程序。 浏览器钱包集成遵循钱包标准模式.

### 高级手动设置

对于需要全面控制RPC和签名人的高级使用案例:

```typescript
import { SolanaKitAdapter } from '@circle-fin/adapter-solana-kit'
import { createSolanaRpc, generateKeyPairSigner } from '@solana/kit'

// Use your existing @solana/kit setup
const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com')
const signer = await generateKeyPairSigner()

// Create the adapter
const adapter = new SolanaKitAdapter({
  rpc,
  signer,
})
```

## 下一个Generation API(`/next`(中文(简体) )

> **预览** - 电话 `/next` 入口是即将到来的默认适配器架构. 它与目前所支持的桥梁流量的切入点相当,并且与所有现有工具包(Bridge Kit等)完全兼容。 在下一个主要发布, `/next` 将会成为默认的导入,当前切入点将会被退出。 见 [目前的限制 `/next`](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-current-limitations-of-next) 在通过之前.

### 开始 `/next`

通过改变单一导入路径来切换到新架构. 其他一切不变:

```typescript
import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit/next'

const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!, // Base58, Base64, or JSON array
})

// Pass it to the Bridge Kit exactly as before — no changes needed downstream
```

浏览器钱包工作相同 :

```typescript
import { createSolanaKitAdapterFromProvider } from '@circle-fin/adapter-solana-kit/next'

const adapter = await createSolanaKitAdapterFromProvider({
  provider: window.solana, // Phantom, Solflare, etc.
})
```

### 为什么 `/next`? 吗?

|  | 当前切入点 | `/next` 切入点 |
| --- | --- | --- |
| **套装大小** | 包含全部适配器 | 私人进口 解锁树摇; 默认工厂仍然拉 compat shim — 看 [捆绑大小](https://npmcn.com/package/%40circle-fin/adapter-solana-kit/#readme-bundle-size-note) |
| **准备结果** | `estimate()` 财务报告和审定财务报表 `execute()` | `estimate()`, (中文(简体) ), `simulate()`,以及 `execute()` |
| **收费模式** | 适应器特定形状 | `{ fee, units, unitPrice }` ——所有生态系统保持一致 |
| **观察性** | 不详 | 内建伐木、计量和事件仪器 |
| **重试恢复能力( R)** | 不详 | 可配置重试, 以指数倒置表示短暂的失败 |
| **调制解析** | 硬码地址 | 累加式符号登记——用符号解决任何符号跨链 |
| **交易调试** | 固定默认 | 配置确认超时和重试政策 |

### 套装大小注释

这个 `/next` 入口的清洁建筑设计 按原产地计算可动摇树:进口 `createPrepare` 无 `createBatchExecute` 只能运送准备路径。 单位 当前预览释放默认 `createAdapter` 工厂仍然 牵扯在遗产 compat shim (`withLegacyCompat` → `@core/adapter-compat`消费者可以通过 生成的适配器与现有工具包和提供者不作改动. 那闪电是默认的 `/next` 捆绑量度~11% 大于我们内部基准中遗留的切入点.

如果捆绑大小对您至关重要,则直接通过 `assembleAdapter` 从 `@core/adapter-base` 跳过 `withLegacyCompat`。未来微小的释放将分裂共通 在单独的入口后面,所以默认的工厂 仅新建 API.

### 目前的限制 `/next`

这个 `/next` 索拉纳 Kit 适配器与当前切入点对等 对于支持的桥梁流量,但有一些警告。 他们是 在项目问题跟踪器中跟踪后续发布情况:

-   **圆形钱包适配器尚未迁移到 `/next`。 。 。 .** 仅 eVM (viem/ethers) 和索拉纳适配器显示 `/next` 入场点; 圆形钱包留在目前的出入口上.
-   **中止语义只停止本地等待 .** 通过中止(或 可中止) `signal` 取消数 `waitForTransaction` 并预防 未经同意 `execute` 从广播,但 **一经交易 播放, 中止不会在链上取消** 交易 继续,并应当通过签署实现和解.

### 已编制交易:估计、模拟、执行

当您准备通过 `/next` 适配器,你用三种生命周期方法返回更丰富的对象:

```typescript
const prepared = await adapter.prepare(
  {
    instructions: [transferInstruction],
    feePayer: payerPublicKey,
  },
  { chain: 'Solana' },
)

// 1. Estimate fees before committing
const { fee, units, unitPrice } = await prepared.estimate()

// 2. Simulate the transaction to catch errors without spending fees
const simulation = await prepared.simulate()

// 3. Execute when ready
const result = await prepared.execute()

// `result` is a `{ txId, wait }` envelope:
// - `txId` is the transaction signature (base58 string on Solana —
//   named `txId` for cross-ecosystem symmetry with the EVM adapters).
// - `wait()` resolves once the transaction is confirmed on the cluster.
console.log('submitted signature:', result.txId)
const confirmation = await result.wait()
```

这个 `simulate()` 步骤是新建的 `/next` ——它根据当前分类账状态对交易进行干燥并浮出错误来支付交易费.

### 日志

传出 a `runtime` 选项以获取每个适配器操作的结构化日志,包括 RPC 调用、重试和出错。 最快的方法是使用内置 `createRuntime` 帮助者 :

```typescript
import {
  createSolanaKitAdapterFromPrivateKey,
  createRuntime,
} from '@circle-fin/adapter-solana-kit/next'

const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  runtime: createRuntime(), // Logs to stdout via pino at 'info' level
})
```

要与自己的日志集成, 请通过执行对象 `debug`, (中文(简体) ), `info`, (中文(简体) ), `warn`, (中文(简体) ), `error`,以及 `child` 改为 `createRuntime`。日志接口使用 `(message, fields)` 参数顺序——皮诺等库使用 `(fields, message)`,所以需要一个薄薄的包装:

```typescript
import {
  createSolanaKitAdapterFromPrivateKey,
  createRuntime,
} from '@circle-fin/adapter-solana-kit/next'
import pino from 'pino'

function wrapPino(p: pino.Logger) {
  return {
    debug: (msg: string, fields?: Record<string, unknown>) =>
      p.debug(fields, msg),
    info: (msg: string, fields?: Record<string, unknown>) =>
      p.info(fields, msg),
    warn: (msg: string, fields?: Record<string, unknown>) =>
      p.warn(fields, msg),
    error: (msg: string, fields?: Record<string, unknown>) =>
      p.error(fields, msg),
    child: (tags: Record<string, unknown>) => wrapPino(p.child(tags)),
  }
}

const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  runtime: createRuntime({ logger: wrapPino(pino({ level: 'debug' })) }),
})
```

### 计量

这个 `runtime` 选项还接受 `metrics` 用于计数器、直方图和计时器的执行。 插入普罗米修斯,StatsD, Datadog, OpenTeleometry, 或任何其他后端 :

```typescript
import {
  createSolanaKitAdapterFromPrivateKey,
  createRuntime,
} from '@circle-fin/adapter-solana-kit/next'

const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  runtime: createRuntime({
    metrics: {
      counter: (name) => ({
        inc: (labels, value) => {
          /* emit counter */
        },
      }),
      histogram: (name) => ({
        observe: (labels, value) => {
          /* emit histogram */
        },
      }),
      timer: (name) => ({
        start: (labels) => {
          const t0 = Date.now()
          return () => {
            /* observe Date.now() - t0 */
          }
        },
      }),
      child: (labels) => {
        /* return scoped Metrics with base labels merged */
      },
    },
  }),
})
```

否时 `metrics` 平面电话是无声的 无声的 零起落.

### 托肯书记官处

默认情况下,适配器知道USDC(和其他内置符)在每个支持链上的情况. 这个 `tokens` 选项允许您注册额外的符号,以便它们可以通过符号而不是原始地址来引用.

```typescript
import {
  createSolanaKitAdapterFromPrivateKey,
  createTokenRegistry,
} from '@circle-fin/adapter-solana-kit/next'

const tokens = createTokenRegistry({
  tokens: [
    {
      symbol: 'BONK',
      decimals: 5,
      locators: {
        Solana: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263',
      },
    },
  ],
})

const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  tokens,
})
```

登记册自动解决每个链条的正确程序地址和小数,因此下游代码可以指: `'BONK'` 而不是硬编码薄荷地址.

### 交易调制

这个 `config` 选项允许您调制重试行为和确认超时 :

```typescript
import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit/next'

const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  config: {
    transaction: {
      confirmationTimeoutMs: 60_000, // 60 second confirmation timeout
    },
    retry: {
      maxAttempts: 5,
      baseDelayMs: 500,
    },
  },
})
```

| 设置 | 它控制着什么 | 默认 |
| --- | --- | --- |
| `confirmationTimeoutMs` | 多长时间 `waitForTransaction` 等待时间结束 | 客户违约 |
| `retry.maxAttempts` | 最大尝试次数( 不包括初始尝试) | `3` |
| `retry.baseDelayMs` | 以毫秒为单位的重试之间的基数延迟( 每次重试时通过指数倒置) | `200` |

设定 `retry: false` 完全禁用自动重试.

### 迁移路径

这个 `/next` 入站点设计为零平移:

1.  **现在** - 从 `@circle-fin/adapter-solana-kit/next`. 返回的适配器与所有现有的工具包和提供者完全兼容——他们方面不需要改动.
2.  **下一个主要发布** - 电话 `/next` 架构成为默认条目(`@circle-fin/adapter-solana-kit`) (中文(简体) ). 当前基于类的适配器将被删除.

**我需要改变什么?**

-   将导入路径更改为 `@circle-fin/adapter-solana-kit/next`。 。 。 .
-   这个 `chain` 参数已经从工厂中删除。 链条现在通过 `capabilities.supportedChains` (默认情况下所有索拉纳链)和指定的操作通过 `OperationContext`。 。 。 .
-   如果只将适配器传递给一个工具包,工具包会自动处理链选择——不需要其他修改.

## 特征

-   ✅ **完全索拉纳兼容性** - 与索拉纳主网和德文网合作
-   ✅ **@ solana/ kit 整合** - 使用有树摇动支持的现代功能性API
-   ✅ **钱包提供者支持** - 与幽灵、索尔夫拉尔和其他索拉纳钱包合作
-   ✅ **工厂方法** - 容易设置和合理默认
-   ✅ **交易周期** - 使用@solana/kit模式完成编制/估计/执行工作流程
-   ✅ **类型安全** - 严格模式的完整类型脚本支持
-   ✅ **跨链准备** - 索拉纳链和EVM链之间的无缝接通USDC

## 用法实例

### 工厂方法的基本使用

```typescript
import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit'
import { BridgeKit } from '@circle-fin/bridge-kit'

// Create adapter with factory method - supports multiple key formats!
const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!, // Accepts Base58, Base64, or JSON array
})

// Use directly with App Kit
const kit = new BridgeKit()
const result = await kit.bridge({
  from: { adapter: evmAdapter, chain: 'Base' },
  to: { adapter, chain: 'Solana' },
  amount: '10.50',
  token: 'USDC',
})
```

### 多密钥格式支持

这个 `createSolanaKitAdapterFromPrivateKey` 函数自动检测和处理不同的私钥格式:

```typescript
// Base58 format (most common for Solana)
const adapterBase58 = createSolanaKitAdapterFromPrivateKey({
  privateKey: '5Kk7z8gvn...', // Base58 string
})

// Base64 format
const adapterBase64 = createSolanaKitAdapterFromPrivateKey({
  privateKey: 'MIGHAgEAMB...', // Base64 string
})

// JSON array format (array of bytes)
const adapterArray = createSolanaKitAdapterFromPrivateKey({
  privateKey: '[1,2,3,4,5,...]', // JSON array string
})
```

### 横琴桥(EVM-索拉纳)

```typescript
import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
import { BridgeKit } from '@circle-fin/bridge-kit'

const kit = new BridgeKit()

// EVM source adapter
const evmAdapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.EVM_PRIVATE_KEY as `0x${string}`,
})

// Solana destination adapter
const solanaAdapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
})

// Execute cross-chain bridge operation
const result = await kit.bridge({
  from: { adapter: evmAdapter, chain: 'Base_Sepolia' },
  to: { adapter: solanaAdapter, chain: 'Solana_Devnet' },
  amount: '10.50',
  token: 'USDC',
})
```

### 浏览器钱包集成

```typescript
import { createSolanaKitAdapterFromProvider } from '@circle-fin/adapter-solana-kit'
import { BridgeKit } from '@circle-fin/bridge-kit'

// Connect to user's Solana wallet
const adapter = await createSolanaKitAdapterFromProvider({
  provider: window.solana, // Phantom, Solflare, etc.
})

// Use with App Kit
const kit = new BridgeKit()
const result = await kit.bridge({
  from: { adapter: evmAdapter, chain: 'Base' },
  to: { adapter, chain: 'Solana' },
  amount: '50.0',
  token: 'USDC',
})
```

### 用 @ solana/ kit 客户端进行手动设置

```typescript
import { SolanaKitAdapter } from '@circle-fin/adapter-solana-kit'
import { BridgeKit } from '@circle-fin/bridge-kit'
import { createSolanaRpc, generateKeyPairSigner } from '@solana/kit'

// Initialize with your @solana/kit setup
const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com')
const signer = await generateKeyPairSigner()

const adapter = new SolanaKitAdapter({
  rpc,
  signer,
})

// Use directly with App Kit
const kit = new BridgeKit()
const result = await kit.bridge({
  from: { adapter: evmAdapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Solana' },
  amount: '10.50',
  token: 'USDC',
})
```

## 支持的网络

与App Kit支持的所有索拉纳网络合作:

-   **索拉纳主网** - 生产网络
-   **索拉纳·德夫内** - 开发和测试网络

## API 参考

### 工厂方法

#### `createSolanaKitAdapterFromPrivateKey(options)`

从私钥创建适配器(支持多格式).

```typescript
interface CreateAdapterFromPrivateKeyParams {
  privateKey: string // Supports Base58, Base64, or JSON array formats
  getRpc?: (params: { chain: ChainDefinition }) => Rpc<SolanaRpcApi> // Custom RPC factory
  capabilities?: AdapterCapabilities // Optional addressContext and supportedChains
}
```

#### `createSolanaKitAdapterFromProvider(options)`

从 Solana 钱包提供者创建适配器 .

```typescript
interface CreateAdapterFromProviderParams {
  provider: SolanaKitWalletProvider // Phantom, Solflare, etc.
  getRpc?: (params: { chain: ChainDefinition }) => Rpc<SolanaRpcApi> // Custom RPC factory
  capabilities?: AdapterCapabilities // Optional addressContext and supportedChains
}
```

### 构造选项

```typescript
interface SolanaKitAdapterOptions {
  getRpc: (params: {
    chain: ChainDefinition
  }) => Promise<Rpc<SolanaRpcApi>> | Rpc<SolanaRpcApi>
  getSigner: (
    ctx: OperationContext,
  ) => TransactionSigner | Promise<TransactionSigner>
}
```

**缓存性能( P) :**

适配器为 RPC 客户端和签名人执行智能缓存:

-   **RPC 缓存**: RPC 客户端每个链被缓存以防止冗余初始化
-   **签名人缓存**:每个操作上下文都缓存签名符(基于链和地址),以避免为同一上下文重新创建签名符
-   **同时安全**: 两种缓存机制均优雅地处理并行呼叫,防止重复初始化

这保证了在与多个链条或操作背景合作时的最佳性能.

### 方法

-   `getAddress()` - 获取连接的钱包地址
-   `getChain()` - 获取链条信息
-   `prepare()` - 使用@solana/ kit模式准备执行交易
-   `estimate()` - 估计交易费用
-   `execute()` - 执行已准备好的交易
-   `waitForTransaction()` - 等待交易确认
-   `calculateTransactionFee()` - 用可选缓冲器计算交易费

### 额外出口

**CCTP 整合 :**

-   `CctpActionBuilder`, (中文(简体) ), `SolanaAction` - CCTP行动接口
-   `CoreCctpActionBuilder` - CCTP核心逻辑与@solana/kit之间的桥梁

**公用事业:**

-   `convertInstruction`, (中文(简体) ), `convertInstructions` - 将 Web3.js 指令转换为 @ solana/ kit 格式

您可以在索拉纳 Kit Adapter 的主要执行文件中看到每种方法的实施.

## 建筑

### 与 @ solana/web3.js 的密钥差异

@solana/kit代表着从基于班级到功能编程模式的完整的建筑转变:

| **类别** | **@solana/web3.js (法语)** | **@solana/kit 3.0.2(现代)** | **移徙影响** |
| --- | --- | --- | --- |
| **RPC 客户端** | `new Connection(rpcUrl)` | `createSolanaRpc(rpcUrl)` | RPC 代理对象 |
| **签名人** | `Keypair.fromSecretKey()` | `generateKeyPairSigner()` | 原始加密 APIs |
| **地址** | `new PublicKey(string)` | `address(string)` | 品牌类型系统 |
| **交易** | `Transaction.add(ix)` | `pipe(createTransactionMessage, append)` | 职能组成 |
| **签名** | `transaction.sign(signer)` | `signTransactionMessageWithSigners(tx)` | 自签名消息 |
| **说明** | `TransactionInstruction` | `Instruction` 有角色元数据 | 加强账户作用 |
| **执行** | `connection.sendTransaction()` | `rpc.sendTransaction().send()` | 代理方法调用 |

### 效益 [@ solana/ kit (英语)](https://www.npmjs.com/package/@solana/kit) 建筑

-   **树能震动**: 完整的库可以是树形折叠的,会大幅缩小捆绑大小
-   **原生密码**: 流水浏览器内置 `CryptoKeyPair` 财务报告和审定财务报表 `SubtleCrypto` APIs 密码
-   **不可改变**: 具有不可改变的交易信息构建功能模式
-   **可编曲**: 基于管道 `pipe()` 交易结构
-   **基于代理**: 动态 RPC 方法构建无论API 覆盖范围如何,都保持捆绑大小常数

### 交易楼模式

```typescript
import {
  pipe,
  createTransactionMessage,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
} from '@solana/kit'

// Functional transaction building with immutable message construction
const transactionMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (tx) => setTransactionMessageFeePayerSigner(signer, tx),
  (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
  (tx) => appendTransactionMessageInstruction(instruction, tx),
)

// Self-signing transaction messages
const signedTransaction =
  await signTransactionMessageWithSigners(transactionMessage)

// Send using RPC proxy
await rpc.sendTransaction(signedTransaction, { encoding: 'base64' }).send()
```

## 与 App Kit 整合

这个适配器的设计可以无缝地跨越App Kits生态系统. 举个例子 [桥套](https://www.npmjs.com/package/@circle-fin/bridge-kit)数字 :

```typescript
import { BridgeKit } from '@circle-fin/bridge-kit'
import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new BridgeKit()

// Solana adapter
const solanaAdapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
})

// EVM adapter
const evmAdapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.EVM_PRIVATE_KEY as `0x${string}`,
})

// Bridge from EVM to Solana
const result = await kit.bridge({
  from: { adapter: evmAdapter, chain: 'Ethereum' },
  to: { adapter: solanaAdapter, chain: 'Solana' },
  amount: '50.0',
  token: 'USDC',
})
```

## 发展

这个包是App Kits monorepo的一部分.

```bash
# Build
nx build @circle-fin/adapter-solana-kit

# Test
nx test @circle-fin/adapter-solana-kit
```

## 许可证

这个项目根据Apache 2.0许可证获得许可. 联系人 [支助](https://help.circle.com/s/submit-ticket) 详细情况.

* * *

**准备好了吗?**

[加入磁盘](https://discord.com/invite/buildoncircle) 二. 支助 [访问我们的救世主](https://help.circle.com/s/submit-ticket)

_由 Circle 创建_

## 常见问题

### @circle-fin/adapter-solana-kit 是什么？

索拉纳区块链适配器由@solana/kit供电

### 如何安装 @circle-fin/adapter-solana-kit？

在项目目录运行 npm install @circle-fin/adapter-solana-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@solana/kit（^5\.0\.0）、@solana/web3\.js（^1\.98\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @circle-fin/adapter-solana-kit 支持 TypeScript 吗？

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

### @circle-fin/adapter-solana-kit 支持 ESM 还是 CommonJS？

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

### @circle-fin/adapter-solana-kit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @circle-fin/adapter-solana-kit 可以商用吗？

@circle-fin/adapter-solana-kit 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @circle-fin/adapter-solana-kit 的下载量有多少？

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

### @circle-fin/adapter-solana-kit 还在维护吗？

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