# @gumag/bridge 中文文档

规范地址：https://npmcn.com/package/%40gumag/bridge/

版本：0\.1\.0
npm 元数据更新时间：2026-11-05T03:29:18.261Z
中文译文更新时间：2026-11-17T08:08:39.405Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gumag/bridge
原文对照：https://npmcn.com/package/%40gumag/bridge/?lang=original
项目主页：https://docs.gum.ag/universal-bridge/v2/quickstart

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

- 包体积（解压后）：405 kB，49 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- peer 依赖：viem \>=2\.33\.1 \<3，@mysten/sui \>=2\.26\.2 \<3，@solana/web3\.js \>=1\.98\.0 \<2
- 首次发布：2026-11-05T03:27:40.839Z
- 最新版本发布：2026-11-05T03:29:18.076Z
- 近 30 天下载量：4993（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

在EVM链,索拉纳和苏伊之间用GUM桥 API进行交换和桥接:引出,用用户的钱包执行,表.

## 安装

```sh
npm install @gumag/bridge
```

也可以使用：`pnpm add @gumag/bridge`、`yarn add @gumag/bridge`、`bun add @gumag/bridge`

## README

# @ gumag/ 桥牌

在EVM链,索拉纳和苏伊之间用用户自己的钱包进行交换并搭桥. 这个 [GUM 桥型 API](https://docs.gum.ag/universal-bridge/v2/overview) 选择 路径, 构建每个交易和跟踪执行; 此软件包询问 钱包来签名并告诉API它签了什么.

```ts
import { createBridge } from "@gumag/bridge";

const bridge = createBridge();
const quote = await bridge.quote({
  from: { chain: "evm:8453", token: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" },
  to: { chain: "evm:42161", token: "0xaf88d065e77c8cc2239327c5edb3a432268e5831" },
  amount: "100",
  sender, recipient,
});
const order = await bridge.execute(quote, { wallet: window.ethereum });
for await (const status of bridge.watch(order.id)) render(status);
```

```sh
npm install @gumag/bridge
```

`viem`, (中文(简体) ), `@solana/web3.js` 1.x和 `@mysten/sui` 是同伴的依赖关系,所以 您的应用程序的复制件是共享的: npm 和 pnpm 安装任何缺失的(与 雅恩,你自己加起来.

## 钱包

传出传输的链条的钱包 .

| 从 | `wallet` |
| --- | --- |
| EVM( 视频) | EIP-1193供应商: `window.ethereum`,或 `await connector.getProvider()` 与瓦格米语 |
| 索拉纳 | 钱包适配器( E)`useWallet()`)或注入的提供者 `signTransaction` 或者说 `signAndSendTransaction` |
| 苏 | `{ signAndExecuteTransaction }` 从dapp -kit's的 `useSignAndExecuteTransaction()` |

钱包必须持有 `sender`。 。 。 . `execute` 将 EVM 钱包切换到右边 网络(如果钱包不知道则添加),然后提示每一步一次: 一个提示索拉纳和苏伊 两个提示EVM 当信物需要批准时. 每个签名步骤立即向API报告. `execute` 当 钱已经离开了钱包,有命令 `executing`· ; `watch` 跟着它 `delivered`, (中文(简体) ), `refunded`, (中文(简体) ), `failed` 或者说 `expired`。 。 。 .

## 检查什么

API 构建每笔交易. 在任何提示之前,这个包检查 未知路由器的顺序 :

-   仅保留一个引号 用于要求的金额和信物 及其顺序 一定和它相符。 每一步都在网络上 由 `sender`。 。 。 .
-   在EVM上,批准发送的代号不超过金额,以及 没有其它呼叫授权或移动符或钱包本身。 土著 价值和批准额,按订单汇总,不超出金额.
-   在索拉纳和苏伊,没有交易 交出一个账户或整个 余额:无重新调配或非锁入账户,象征性授权变更, 刻录、批准超过金额、向他人关闭账户或 苏伊毒气钱币的转让.
-   索拉纳钱包可以为此包的交易添加优先收费 发送; 拒绝任何其它更改 。 API 发送的交易, 或一项 另外一个已经签名的签名人,必须完全如所建.
-   押金定单会给地址寄出确切的代币金额 名字,没有别的.
-   没有步骤是两次签字,一旦签字开始,命令就不能获得步骤.

路由器自己的合同或程序 与它发送的是 API的选择;钱包的交易预览是最后一次检查.

## 执行选项

`execute(quote, { wallet, signal, onOrder, onSubmitted, onStep })`数字 :

-   `wallet` 是提供者或适配器,或 `{ signers }` 当您的应用程序已经 在桥的外形上摆放签名者.
-   `signal` 在下一个钱包提示前取消; 已经发送的资金是 仍在报告.
-   `onSubmitted` 当资金交易离开钱包时即开火,或者 在通知API之前,为API发送签名。 坚持下去 在此处转移( e)`order.id`, (中文(简体) ), `step.n`, (中文(简体) ), `txHash`: 失败的报表无法 输了.
-   `onStep` 点火时,每个提示打开,一旦报告,即发出命令.

每个步骤都是在API最后一次返回时从订单上签名的,所以API 可以调整大小或重建每份报告后剩下的要签名的内容。 报告 API在1 s 和 3 s 之后不再回答;如果它仍然失败, `execute` 掷出 `report-failed`,以及 `reportStep(orderId, n, txHash)` 发送 稍后(两次报告无所改变)。 API 费率限额的命令 创建于 `Retry-After` 最多15 s. (中文(简体) ). 一旦一个资助步骤到达钱包,没有明确拒绝,命令 同样的引用再次从相同的 `createBridge()` 客户端抛出 `report-failed` 而不是催促两次.

## 链条、指使和金额

-   `chain`: 来自 `chains()`数字 : `evm:8453`, (中文(简体) ), `solana:mainnet`, (中文(简体) ), `sui:mainnet`。 。 。 .
-   `token`: 合同地址 `tokens()`,或 `native` 汽油硬币.
-   `amount`: 符号单位中的十进制(`"100"`, (中文(简体) ), `"0.5"`),或基数单位 作为 `bigint` (单位:千美元)`100000000n`) (中文(简体) ). 超过符号的十进制是一个错误, 从来没有四舍五入.
-   `slippageBps`:可选. 5个bps在两个之间 美元稳定币(美元兑美元,美元兑美元),120桶 (e) 其他(ETH至ETH),GUM环球交换报价为2%,其下限; 每一个引用 `slippageBps` 说什么应用。 设定为每个路线 向一种宽容.

引用是最佳路线 每一个路线,最好的第一,下 `alternatives`. 数额是基数单位`amountOut`),并在 `decimal` (单位:千美元)`decimal.amountOut`) (中文(简体) ). 任何选择都可以传递给 `execute`。 。 。 .

## 错误

所有东西都抛出 `BridgeError` 带有 `code`页:1 `order` 一旦出现 1,钱包的,节点的或请求的自身错误为 `cause`。 。 。 .

| `code` | 怎么办 |
| --- | --- |
| `quote-expired` | 复举出相. |
| `order-uncertain` | 较早的尝试可能与路由器一起持有此引文. 复举出相. |
| `wallet-rejected` | 无所寄出. 运行 `execute` 重复, 引用会持续. |
| `wallet-missing` | 把钱包递给我 `sender`,用于源链. |
| `wallet-network` | 钱包不在源网络上,无法切换. 无所寄出. |
| `insufficient-gas` | 钱包不能支付网络费. 无所寄出. |
| `simulation-failed` | 钱包或网络说会失败 没有被发送; 尝试另一个路径 . |
| `wallet-changed` | 钱包编辑了超过优先级收费的交易 。 无所寄出. |
| `wallet-failed` | 钱包失败 。 除非 `onSubmitted` 被开除了. |
| `unknown-chain`, (中文(简体) ), `unknown-token` | 使用来自 `chains()` 和地址来自 `tokens()`。 。 。 . |
| `no-route` | 现在没有路由器携带这对或数量; `failures` 说为什么. |
| `price-unavailable` | 没有价钱来核对最低价 再试一试. |
| `invalid-order` | 一步失败的安全检查。 没有签名. |
| `step-out-of-order`, (中文(简体) ), `step-conflict` | 另一个标签正在运行此命令 。 跟着它 `watch`。 。 。 . |
| `report-failed` | 剩下的资金,但API没有被告知。 打电话 `reportStep()`别再签了. |
| `rate-limited`, (中文(简体) ), `unavailable` | 重试, 之后 `retryAfter` 设定时秒; `watch` 等待这些出来. |

## 他们一到就引用

`quote()` 一旦每个路由器都有答案. `stream()` 打开 WebSocket 并 每次路由器回答或刷新时,都会生成一个快照,每个都是一样的 `quotes` 形状、 完整和最佳第一:

```ts
const controller = new AbortController();
for await (const snapshot of bridge.stream(request, { signal: controller.signal })) {
  render(snapshot.quotes, snapshot.pending); // replace, never append
}
```

API 大约五分钟后关闭套接字; 呼叫 `stream()` 再来一次. 任何快照的引文都可以读到 `execute()`。需要一个全球 `WebSocket` (浏览器,节点22+).

在钱包连接之前, 省略 `sender` 财务报告和审定财务报表 `recipient`数字 : `quote()` 财务报告和审定财务报表 `stream()` 然后只返回价格,引用没有 `id` 那个 `execute()` 拒绝。 连接后再次用两个钱包引用.

## 其他电话

```ts
const { chains, routers } = await bridge.chains();
const { tokens } = await bridge.tokens({ chain: "evm:8453", query: "USDC" });
const order = await bridge.getOrder(id);
createBridge({ apiKey: "…", baseUrl: "https://bridge-api.gum.ag" });
```

`routers` 是路由器 您的键的引号可以来自, 每个与 `name` 财务报告和审定财务报表 `logo` 运输路线`mono` 绘制为暗页 : 在第一个引文之前显示它们,然后添加一个路由器,然后用 你那边没有变化.

没有 `apiKey` 你得到公共路线简介。 收据和索拉纳 广播通过GUM的公共RPC代理,所以不需要RPC密钥.

## 软件包

只有无害环境管理,有类型. `dist/` 类型脚本在 `src/` 编译出一个文件 每个模块,没有精密化,有源图, 和两个船在包。 这个 没有安装脚本. `createBridge()` 并引用未装入库 第一次签名代码和链式库加载 `execute()`。 。 。 .

## 许可证

麻省理工学院.

## 常见问题

### @gumag/bridge 是什么？

在EVM链,索拉纳和苏伊之间用GUM桥 API进行交换和桥接:引出,用用户的钱包执行,表\.

### 如何安装 @gumag/bridge？

在项目目录运行 npm install @gumag/bridge，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（\>=2\.33\.1 \<3）、@mysten/sui（\>=2\.26\.2 \<3）、@solana/web3\.js（\>=1\.98\.0 \<2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gumag/bridge 支持 TypeScript 吗？

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

### @gumag/bridge 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gumag/bridge 需要什么版本的 Node\.js？

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

### @gumag/bridge 可以商用吗？

@gumag/bridge 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gumag/bridge 的下载量有多少？

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

### @gumag/bridge 还在维护吗？

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

