# @ar\.io/wayfinder-core 中文文档

规范地址：https://npmcn.com/package/%40ar.io/wayfinder-core/

版本：2\.0\.2
npm 元数据更新时间：2026-08-13T20:33:16.736Z
中文译文更新时间：2026-11-06T13:24:34.033Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40ar.io/wayfinder-core
原文对照：https://npmcn.com/package/%40ar.io/wayfinder-core/?lang=original
项目主页：https://github.com/ar-io/wayfinder#readme
源码仓库：https://github.com/ar-io/wayfinder

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

- 包体积（解压后）：319 kB，129 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：13 个
- peer 依赖：@ar\.io/sdk \>=4\.0\.0
- 首次发布：2025-06-12T21:10:21.125Z
- 最新版本发布：2026-08-13T20:33:16.332Z
- 近 30 天下载量：3632（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：85（近 12 个月 13 个）

## 中文简介

WayFinder核心库用于智能路由到最佳AR. IO 网关

## 安装

```sh
npm install @ar.io/wayfinder-core
```

也可以使用：`pnpm add @ar.io/wayfinder-core`、`yarn add @ar.io/wayfinder-core`、`bun add @ar.io/wayfinder-core`

## README

# 探险家核心

`@ar.io/wayfinder-core` 是 Wayfinder 项目的核心库。 它提供了通过ar.io网络来进行路由和核实数据的核心功能.

## 快速启动

### 安装

要安装最新版本, 请运行 :

```bash
npm install @ar.io/wayfinder-core
# or
yarn add @ar.io/wayfinder-core
```

### 基本用途

```javascript
import { createWayfinderClient } from '@ar.io/wayfinder-core';

// Creates a Wayfinder client with sensible defaults:
// - Trusted peers gateway provider with caching (5 minute TTL)
// - Random routing strategy
// - Verification disabled
const wayfinder = createWayfinderClient();

// Use Wayfinder to fetch data using ar:// protocol
const response = await wayfinder.request('ar://example-name');
```

### 使用AR.IO网络

```javascript
import {
  createWayfinderClient,
  FastestPingRoutingStrategy,
  NetworkGatewaysProvider,
} from '@ar.io/wayfinder-core';
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc } from '@solana/kit';

// AR.IO Solana mainnet — program-id overrides are not needed on mainnet
// (the SDK ships defaults). For devnet, pass explicit program IDs.
const ario = ARIO.init({
  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
});

const wayfinder = createWayfinderClient({
  routingStrategy: new FastestPingRoutingStrategy({
    gatewaysProvider: new NetworkGatewaysProvider({
      ario,
      sortBy: 'operatorStake',
      sortOrder: 'desc',
      limit: 10,
    }),
  }),
});
```

### 启用校验

```javascript
import {
  createWayfinderClient,
  HashVerificationStrategy,
} from '@ar.io/wayfinder-core';

const wayfinder = createWayfinderClient({
  verificationStrategy: new HashVerificationStrategy({
    trustedGateways: [new URL('https://turbo-gateway.com')],
  }),
  strict: true, // Fail requests on verification errors
});
```

Wayfinder Core为构建路由和核查战略提供辅助功能:

### 创建策略

以简单的字符串标识符创建路由策略 :

```javascript
import { createRoutingStrategy } from '@ar.io/wayfinder-core';

// Create a random routing strategy
const randomStrategy = createRoutingStrategy({
  strategy: 'random',
  gatewaysProvider: myGatewaysProvider,
  logger: myLogger,
});

// Available strategies: 'random', 'fastest', 'balanced', 'preferred'
```

### 创建验证战略

以简单的字符串标识符创建验证策略 :

```javascript
import { createVerificationStrategy } from '@ar.io/wayfinder-core';

// Create a hash verification strategy
const hashStrategy = createVerificationStrategy({
  strategy: 'hash',
  trustedGateways: [new URL('https://turbo-gateway.com')],
  logger: myLogger,
});

// Available strategies: 'hash', 'data-root', 'remote', 'disabled'
```

## ar://礼宾

Wayfinder 支持几种 ar:// URL 格式 :

```bash
ar://TRANSACTION_ID              # Direct transaction ID
ar://NAME                        # ArNS name (paths supported)
ar:///info                       # Gateway endpoint (/info)
```

## 动态运行

向导支持 a `resolveUrl` 生成动态重定向 URL 到目标网关的方法。 此功能可以直接用于替换任何硬码网关URL,取而代之的是使用Wayfinder的路由逻辑来选择请求的网关.

#### ANS 名称

给一个ArNS名称,重定向URL会与原URL相同,但有由Wayfinder的路由策略所选择的网关.

```javascript
const redirectUrl = await wayfinder.resolveUrl({
  arnsName: 'ardrive',
});
// results in https://ardrive.<selected-gateway>
```

#### 交易编号

由于txId,重定向的URL会与原URL相同,但带有由Wayfinder的路由策略所选择的网关.

```javascript
const redirectUrl = await wayfinder.resolveUrl({
  txId: 'example-tx-id',
});
// results in https://<selected-gateway>/example-tx-id
```

#### 遗产 URL

鉴于遗留的arweave.net或arweave.dev URL,重定向的URL会与原URL相同,但与由Wayfinder的路由策略所选择的网关相同.

```javascript
const redirectUrl = await wayfinder.resolveUrl({
  originalUrl: 'https://arweave.net/example-tx-id',
});
// results in https://<selected-gateway>/example-tx-id
```

#### ar://URLs (韩语)

鉴于一个 ar:// URL, 重定向的 URL 会与原 URL 相同, 但有 Wayfinder 的路由策略所选择的网关 .

```javascript
const redirectUrl = await wayfinder.resolveUrl({
  originalUrl: 'ar://example-name/subpath?query=value',
});
// results in https://<selected-gateway>/example-name/subpath?query=value
```

## 网关提供者

网关提供者提供网关列表用于路由. **默认, `createWayfinderClient` 财务报告和审定财务报表 `new Wayfinder()` 使用缓存 `CompositeGatewaysProvider` 尝试 `TrustedPeersGatewaysProvider` 先掉回信任的网关.** 同行发现是一个失败点——一个网关可以回答 `/ar-io/peers` 与 `200` 和一个空的列表——而倒置使请求继续工作(通过一个已经信任的网关)而不是彻底失败. 打电话 `createDefaultGatewaysProvider()` 自己造同样的东西.

| 提供者 | 说明 | 使用大小写 |
| --- | --- | --- |
| `NetworkGatewaysProvider` | 从AR.IO网络返回网关 | 利用AR.IO 带有质量过滤的网络 |
| `TrustedPeersGatewaysProvider` | 从信任的网关端获取 | 动态网关发现( 默认) |
| `StaticGatewaysProvider` | 返回网关的静态列表 | 测试或特定网关 |
| `SimpleCacheGatewaysProvider` | 隐形棺材包装器 | 减少API 调用( 默认使用) |
| `LocalStorageGatewaysProvider` | 浏览器本地缓存 | 持续缓存( 默认用于浏览器) |
| `CompositeGatewaysProvider` | 链条式多供应商倒置 | 多种来源的最大复原力 |

#### 网络Gateways 提供

返回基于链路的ARIO网络的网关列表 [网关地址登记](https://docs.ar.io/learn/gateways/gateway-registry)。您可以指定网关的链上计量标准,以优先排列最高质量网关。 要求数 `@ar.io/sdk` 财务报告和审定财务报表 `@solana/kit`。 。 。 .

```javascript
import { NetworkGatewaysProvider } from '@ar.io/wayfinder-core';
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc } from '@solana/kit';

const ario = ARIO.init({
  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
});

const gatewayProvider = new NetworkGatewaysProvider({
  ario,
  sortBy: 'operatorStake',
  sortOrder: 'desc',
  limit: 10,
  filter: (gateway) => gateway.status === 'joined',
});
```

> **关于排序的说明.** 索拉纳的后端 `@ar.io/sdk` 接受 `sortBy` 财务报告和审定财务报表 `sortOrder` 但不应用它,它的贴花助手会切除账户 以链条顺序列出。 因此,这个供应商将客户端排序,这意味着 它在申请前先阅读整个登记处 `limit`。这就是 `limit: 10` 其实是十个最高的网关 而不是十个 专断的. `sortBy` 并接受点路径, 如 `weights.stakeWeight`; 缺少字段类型的网关 `0`。 。 。 .

#### 信任的PeersGateways 提供工具

从 AR 获取可信任的对等网关的动态列表。 IO网关 `/ar-io/peers` 终点 此提供者对于从可信来源发现可用的网关很有用 .

```javascript
import { TrustedPeersGatewaysProvider } from '@ar.io/wayfinder-core';

const gatewayProvider = new TrustedPeersGatewaysProvider({
  trustedGateway: 'https://turbo-gateway.com',
  retries: 3, // optional, defaults to 3
});
```

一个网关可以回答 `/ar-io/peers` 与 `200` 和一个空的 `gateways` 地图——在 当一个实例没有同步其对登记处的看法时,就会发生这种情况. 在此情况下, 提供者重复, 如果列表仍然是空的, 则丢入 命名终点而不是返回错误 `[]` (会浮出水面) 稍后作为不透明的“ 无网关可用” 从任何路由策略 已经消耗了。 两者 `CompositeGatewaysProvider` 财务报告和审定财务报表 `SimpleCacheGatewaysProvider` 将这个投出当作回倒的信号, 将这个提供者包入其中之一 一个让你有一条干净的堕落之路.

#### 复合通道提供

将多个网关提供者连在一起,按顺序对每个网关进行测试,直到成功。 这对于建立具有弹性的网关发现和后退很有用.

**如何运作:**

1.  按提供顺序给每个供应商打个电话
2.  如果提供者返回一个非空的网关列表,则使用这些网关
3.  如果提供者扔出错误或返回空列表,请移动到下一个提供者
4.  如果所有提供者都失败, 则丢出错误

```javascript
import {
  CompositeGatewaysProvider,
  NetworkGatewaysProvider,
  StaticGatewaysProvider,
  TrustedPeersGatewaysProvider,
} from '@ar.io/wayfinder-core';
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc } from '@solana/kit';

const ario = ARIO.init({
  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
});

// Example: Network-first with static fallback
const gatewayProvider = new CompositeGatewaysProvider({
  providers: [
    // Try fetching from AR.IO network first
    new NetworkGatewaysProvider({
      ario,
      sortBy: 'operatorStake',
      limit: 10,
    }),
    // Fallback to trusted peers if network fetch fails
    new TrustedPeersGatewaysProvider({
      trustedGateway: 'https://turbo-gateway.com',
    }),
    // Final fallback to static list
    new StaticGatewaysProvider({
      gateways: ['https://turbo-gateway.com', 'https://g8way.io'],
    }),
  ],
});
```

## 例行战略

Wayfinder 支持多个路由策略,为您的请求选择目标网关.

| 战略 | 说明 | 使用大小写 |
| --- | --- | --- |
| `RandomRoutingStrategy` | 从列表中选择随机网关 | 有利于负载平衡和弹性 |
| `StaticRoutingStrategy` | 总是使用单一的网关 | 需要使用特定网关时 |
| `RoundRobinRoutingStrategy` | 选择按圆周期顺序排列的网关 | 有利于负载平衡和弹性 |
| `FastestPingRoutingStrategy` | 根据 Ping 时间选择最快的网关 | 善于表现和耐久 |
| `PingRoutingStrategy` | 在失败时用不同的网关重试 | 过滤未响应的网关 。 默认使用 `new Wayfinder()` |
| `PreferredWithFallbackRoutingStrategy` | 使用首选网关, 如果首选网关没有可用, 则使用倒置策略 | 良好的性能和韧性。 对管理自己门户的建筑者来说是理想的. |
| `SimpleCacheRoutingStrategy` | 为 TTL 设置另一个策略所选择的网关 | 避免在每次请求中重运行选择 |
| `CompositeRoutingStrategy` | 将多个路由策略连在一起,按顺序尝试,直到成功 | 适合复杂的后退情景和最大限度的复原能力 |

#### 随机循环战略

从网关列表中选择随机网关.

```javascript
import { RandomRoutingStrategy } from '@ar.io/wayfinder-core';

const strategy = new RandomRoutingStrategy({
  gatewaysProvider: myGatewaysProvider,
});
```

#### 最快的接力战略

根据平分时间选择最快的网关。 此策略会拨打所有可用的网关, 并选择时间最短的网关 .

```javascript
import { FastestPingRoutingStrategy } from '@ar.io/wayfinder-core';

const strategy = new FastestPingRoutingStrategy({
  timeoutMs: 1000,
  gatewaysProvider: myGatewaysProvider,
  probePath: '/', // optional, defaults to '/'
});
```

#### 平陆战略

环绕另一个策略,检查其选择的出入口,用一个 如果检查失败, 则不同 。 这是默认策略 `new Wayfinder()` (编) `RandomRoutingStrategy`) (中文(简体) ).

```javascript
import { PingRoutingStrategy, RandomRoutingStrategy } from '@ar.io/wayfinder-core';

const strategy = new PingRoutingStrategy({
  routingStrategy: new RandomRoutingStrategy({ gatewaysProvider: myGatewaysProvider }),
  retries: 5, // optional
  timeoutMs: 1000, // optional
  probePath: '/', // optional
});
```

**被探测到的.** 双打策略都发出 `HEAD` 改为 `probePath` 编辑 网关自己的主机——而不是正在路由中的请求的沙箱URL. 测试内容 URL 使得网关在解析数据之前, 因此,一个短暂的超时结束 测量“ 是否此天体已经在这里缓存 ” 而不是"是这个网关" 以1s预算对抗直播网络,a `HEAD` 联 合 国 网关根成功对等方为 ~85%,对沙箱为 ~23% 内容 URL - 区别在于暂时性而不是断裂,因为 沙盒式URL在给定10s后达到~78%. 设定 `probePath` 改为 `/ar-io/healthcheck`,或任何你喜欢的路径, 覆盖.

#### 首选的Fall BackRouting战略

使用首选网关, 如果没有首选网关, 则使用倒置策略 。 这对于运行自己的网关并想使用自己的网关作为首选网关的建设者来说是有用的,但同时也想有一个后退策略,以防他们的网关没有.

> \[!INFO\] 这个策略是利用 `CompositeRoutingStrategy` 内部。 它首先尝试拨打首选网关( 使用 : `PingRoutingStrategy` 与 `StaticRoutingStrategy`)),如果失败,则回归到指定的倒置策略.

```javascript
import { PreferredWithFallbackRoutingStrategy, FastestPingRoutingStrategy } from '@ar.io/wayfinder-core';

const strategy = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://my-gateway.com',
  fallbackStrategy: new FastestPingRoutingStrategy({ timeoutMs: 500 }),
});
```

#### 综合战略

这个 `CompositeRoutingStrategy` 允许您将多个路由策略连在一起,通过按顺序尝试每个策略以提供最大回弹力,直到一个策略成功. 这对于复杂的倒置情景来说是理想的,在这种情景中,你想结合不同的路由方法.

**如何运作:**

1.  按提供顺序尝试每个策略
2.  如果策略成功返回一个网关,则使用该网关(剩余策略被跳过)
3.  如果策略出现出错, 请移动到下一个策略
4.  如果所有策略都失败, 则丢出错误

**常用案例:**

-   **业绩+复原力**:先尝试最快的打法,如果打法失败,则倒回随机
-   **首选 + 网络**:先用自有网关,倒回AR. IO 网络选择
-   **多级倒计时**: 尝试溢价网关,然后是标准网关,然后是任何可用的网关

```javascript
import { 
  createWayfinderClient,
  CompositeRoutingStrategy, 
  FastestPingRoutingStrategy, 
  RandomRoutingStrategy,
  StaticRoutingStrategy,
  NetworkGatewaysProvider,
} from '@ar.io/wayfinder-core';
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc } from '@solana/kit';

const ario = ARIO.init({
  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
});

// Example 1: Performance-first with resilience fallback
const performanceWayfinder = createWayfinderClient({
  routingStrategy: new CompositeRoutingStrategy({
    strategies: [
      // Try fastest ping first (high performance, but may fail if all gateways are slow)
      new FastestPingRoutingStrategy({
        timeoutMs: 500,
        gatewaysProvider: new NetworkGatewaysProvider({
          ario,
          sortBy: 'operatorStake',
          limit: 10,
        }),
      }),
      // Fallback to random selection (guaranteed to work if gateways exist)
      new RandomRoutingStrategy({
        gatewaysProvider: new NetworkGatewaysProvider({
          ario,
          sortBy: 'operatorStake', 
          limit: 20, // Use more gateways for fallback
        }),
      }),
    ],
  }),
});

// Example 2: Preferred gateway with multi-tier fallback
const preferredWayfinder = createWayfinderClient({
  routingStrategy: new CompositeRoutingStrategy({
    strategies: [
      // First, try your preferred gateway
      new StaticRoutingStrategy({ 
        gateway: 'https://my-preferred-gateway.com' 
      }),
      // If that fails, try fastest ping from top-tier gateways
      new FastestPingRoutingStrategy({
        timeoutMs: 1000,
        gatewaysProvider: new NetworkGatewaysProvider({
          ario,
          sortBy: 'operatorStake',
          limit: 5, // Only top 5 gateways
        }),
      }),
      // Final fallback: any random gateway from a larger pool
      new RandomRoutingStrategy({
        gatewaysProvider: new NetworkGatewaysProvider({
          ario,
          limit: 50, // Larger pool for maximum availability
        }),
      }),
    ],
  }),
});
```

## 数据检索策略

Wayfinder支持多个数据检索策略从AR获取交易数据. IO网关. 这些战略决定了如何从基础储存层索取并组装数据.

| 战略 | 使用大小写 | 所需资源 |
| --- | --- | --- |
| `ContiguousDataRetrievalStrategy` | 通过直接获取标准数据 | 网关已缓存数据或能够从信任的端点获取数据 |
| `ChunkDataRetrievalStrategy` | 基于 Chunk 的数据组装 | 网关支持 `/chunk/<offset>/data` 端点(r58)并请求交易索引 |

#### 毗连数据检索战略

使用直接获取数据的默认策略 。 这是最直截了当的办法,对大多数案件都有效.

```javascript
import { Wayfinder, ContiguousDataRetrievalStrategy } from '@ar.io/wayfinder-core';

const wayfinder = new Wayfinder({
  dataRetrievalStrategy: new ContiguousDataRetrievalStrategy(),
});
```

#### 春克数据检索策略

先进的战略,通过AR提供的坚固的块API,为装入储存在Arweave节点上的块提供最便捷的方法. IO网关. 这种办法特别有助于:

-   **直接块访问**: 高效地从下方块存储层直接取回数据
-   **捆绑数据项**: 无缝取取自 ANS-104 捆绑内的数据项,使用计算抵销
-   **x402 付款兼容性**: 两种策略都支持自定义获取客户端, 用于基于支付的请求
-   **大型文件处理**: 对可能提出直接请求的大型交易更为可靠

**所需经费:**

-   网关必须支持 `/chunk/<offset>/data` 结束点( 加入 [第58号](https://github.com/ar-io/ar-io-node/releases/tag/r58)(中文(简体) )
-   网关必须设置所要求的交易索引( 直接取自块需要解码)

```javascript
import { Wayfinder, ChunkDataRetrievalStrategy } from '@ar.io/wayfinder-core';

const wayfinder = new Wayfinder({
  dataRetrievalStrategy: new ChunkDataRetrievalStrategy(),
});
```

**如何运作:**

1.  请求获取交易元数据( 根交易ID、 数据抵消、 内容长度)
2.  查询 `/tx/{root-tx-id}/offset` 在编织中获得根交易的绝对相抵
3.  计算请求的数据项的绝对偏移
4.  使用块获取数据 `/chunk/<offset>/data` 并组装完整的数据流
5.  验证属于安全预期根交易的块

**序列图 :**

```mermaid
sequenceDiagram
    participant Client
    participant Wayfinder
    participant Gateway as AR.IO Gateway
    participant Arweave as Arweave Nodes

    Client->>Wayfinder: request('ar://data-item-id')
    activate Wayfinder

    Wayfinder->>Gateway: HEAD /tx/{data-item-id}
    Note over Gateway: Lookup data item metadata<br/>from indexed bundles
    Gateway-->>Wayfinder: Headers:<br/>- x-root-tx-id (bundle ID)<br/>- x-data-offset<br/>- content-length

    Wayfinder->>Gateway: GET /tx/{root-tx-id}/offset
    Gateway->>Arweave: GET /tx/{root-tx-id}/offset
    Note over Arweave: Lookup transaction offset<br/>in the weave
    Arweave-->>Gateway: Root transaction offset
    Gateway-->>Wayfinder: Root transaction offset in weave

    Note over Wayfinder: Calculate absolute offset:<br/>absolute = root_offset + data_offset

    loop For each chunk needed
        Wayfinder->>Gateway: GET /chunk/{absolute-offset}/data
        
        Note over Gateway: Serve chunk data from<br/>indexed storage using<br/>root transaction ID
        
        Gateway-->>Wayfinder: Chunk data + validation headers<br/>(x-root-tx-id for security)
        
        Note over Wayfinder: Validate chunk belongs<br/>to expected root TX
        
        Wayfinder-->>Client: Stream chunk data
    end

    Wayfinder-->>Client: Complete response
    deactivate Wayfinder
```

**创建WayfinderClient 的示例:**

```javascript
import { createWayfinderClient, ChunkDataRetrievalStrategy } from '@ar.io/wayfinder-core';

const wayfinder = createWayfinderClient({
  dataRetrievalStrategy: new ChunkDataRetrievalStrategy(),
});

// Fetch a data item from within an ANS-104 bundle
const response = await wayfinder.request('ar://data-item-id');
```

#### x402 辅助

两种数据检索策略都支持自定义取取执行,允许您使用x402启用取用客户端进行付费网关请求.

```javascript
import { createWayfinderClient, ChunkDataRetrievalStrategy } from '@ar.io/wayfinder-core';
import { createX402Fetch } from '@ar.io/wayfinder-x402-fetch';

const x402Fetch = createX402Fetch({ /* payment config */ });

const wayfinder = createWayfinderClient({
  fetch: x402Fetch,
  dataRetrievalStrategy: new ChunkDataRetrievalStrategy({
    fetch: x402Fetch,
  }),
});
```

## 核查战略

Wayfinder包括确保检索数据完整性的核查机制。 核查战略在复杂性、绩效和安全性之间提供了不同的取舍.

| 验证人 | 复杂性 | 业绩 | 警卫 | 说明 |
| --- | --- | --- | --- | --- |
| `RemoteVerificationStrategy` | 低级 | 低级 | 低级 | 检查 `x-ar-io-verified` 返回数据的网关头 。 若为 `true`,则数据被视为已核实和可信. |
| `HashVerificationStrategy` | 低级 | 高级 | 低级 | 计算返回数据的 SHA-256 散列,并将其比作 a 的散列 **信任的网关** (单位:千美元)_**建议大多数用户使用**_) (中文(简体) ). |
| `DataRootVerificationStrategy` | 中型 | 中型 | 低级 | 计算交易的数据根( 对 L1 交易最有用) 并将其与 a 提供的数据根进行比较 **信任的网关**。 。 。 . |
| `SignatureVerificationStrategy` | 中型 | 中型 | 中型 | \- 说吧 **ANS-104 数据项目**:使用范围请求从信任的网关获取签名组件(所有者,签名类型,标签等),然后按照ANS-104标准使用深度散列计算对数据有效载荷进行签名验证.  
\- 说吧 **L1 交易**:从网关/tx/端点获取交易元数据,从所提供的数据流中计算出数据根,并使用Arweave的加密验证来验证签名. |

#### 远程验证战略

采用这一策略通过检查数据来核实数据 `x-ar-io-verified` 返回数据的网关头 。 如果信头被设定为 `true`,则数据被视为已核实和可信.

> \[大 这一策略只被推荐给用户从自己的网关取来数据,并想避免其他核查策略的间接费用.

```javascript
import { Wayfinder, RemoteVerificationStrategy } from '@ar.io/wayfinder-core';

const wayfinder = new Wayfinder({
  verificationSettings: {
    // no trusted gateways are required for this strategy
    enabled: true,
    strategy: new RemoteVerificationStrategy(),
  },
});
```

#### 质量检验战略

通过SHA-256散列比较验证数据完整性. 这是默认的验证策略,被推荐给大多数寻求安全和性能平衡的用户.

```javascript
import { Wayfinder, HashVerificationStrategy } from '@ar.io/wayfinder-core';

const wayfinder = new Wayfinder({
  verificationSettings: {
    enabled: true,
    strategy: new HashVerificationStrategy({
      trustedGateways: [new URL('https://turbo-gateway.com')],
    }),
  },
});
```

#### 数据旋转验证策略

通过计算交易的数据根来通过Arweave验证数据完整性. 这对L1交易有用,被推荐给希望确保其数据完整性的用户.

```javascript
import { Wayfinder, DataRootVerificationStrategy } from '@ar.io/wayfinder-core';

const wayfinder = new Wayfinder({
  verificationSettings: {
    enabled: true,
    strategy: new DataRootVerificationStrategy({
      trustedGateways: [new URL('https://turbo-gateway.com')],
    }),
  },
});
```

#### 验证战略

验证Arweave交易和数据项目的签名。 从信任的网关取回信头,供核查时使用。 对于一项交易,其数据根在流出其数据时被计算出,然后与其头一起用于核查。 对于数据项,则采用ANS-104深度散列法来验证签名.

```javascript
import { Wayfinder, SignatureVerificationStrategy } from '@ar.io/wayfinder-core';

const wayfinder = new Wayfinder({
  verificationSettings: {
    enabled: true,
    strategy: new SignatureVerificationStrategy({
      trustedGateways: [new URL('https://turbo-gateway.com')],
    }),
  },
});
```

## x402 付款额

可用 Wayfinder 配置与 [x402 付款协议](https://docs.ar.io/learn/gateways/x402-payments#what-is-x402) 提供付费网关服务和更高的费率限制。 这使得您可以无缝地提出可能需要支付的请求,而无需手动处理支付流程.

> \[大 要开始,请安装 `@ar.io/wayfinder-x402-fetch` 软件包.

这个 `@ar.io/wayfinder-x402-fetch` 软件包是一个简单的包装 [x402- 牵引](https://github.com/coinbase/x402/tree/1d4c253aef959b73b46d42e7f0ccf30c7ce64955/typescript/packages/x402-fetch) 库,它创建一个抓取执行,以自动处理x402的支付流量。 您可以通过 Wayfinder 获取执行, 以允许您的请求的x402 支付 .

```javascript
import { createWayfinderClient, StaticRoutingStrategy } from '@ar.io/wayfinder-core';
import { createX402Fetch } from '@ar.io/wayfinder-x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

// Set up your wallet for x402 payments
const privateKey = process.env.X402_PRIVATE_KEY; // Your private key
const account = privateKeyToAccount(privateKey);

// Create x402-enabled fetch implementation
const x402Fetch = createX402Fetch({
  walletClient: account,
});

// Create Wayfinder client with x402 fetch to handle payments
const wayfinder = createWayfinderClient({
  fetch: x402Fetch,
  routingSettings: {
    // Configure to use x402-enabled gateways
    strategy: new StaticRoutingStrategy({
      gateway: 'https://paid-gateway.example.com',
    }),
  },
});

// Requests will now automatically handle x402 payments
const response = await wayfinder.request('ar://transaction-id');
```

**如何运作:**

1.  当网关返回时 `402 Payment Required` 状态
2.  X402 获取自动处理支付流程
3.  申请经重审后发给付款证
4.  你能得到优惠网关服务

**使用大小写 :**

-   对数据请求的较高费率限制
-   使用溢价网关功能
-   通过支付支持网关运营商

为了了解更多x402付款情况,请访问 [x402 文档](https://docs.ar.io/learn/gateways/x402-payments)。 。 。 .

## 事件和监测

#### 全球活动

```javascript
const wayfinder = createWayfinderClient({
  routingSettings: {
    events: {
      onRoutingStarted: (event) => console.log('Routing started:', event),
      onRoutingSucceeded: (event) => console.log('Gateway selected:', event),
    },
  },
  verificationSettings: {
    events: {
      onVerificationProgress: (event) => {
        const percentage = (event.processedBytes / event.totalBytes) * 100;
        console.log(`Verification: ${percentage.toFixed(2)}%`);
      },
      onVerificationSucceeded: (event) => console.log('Verified:', event.txId),
    },
  },
});
```

#### 请求特定事件

```javascript
const response = await wayfinder.request('ar://example', {
  verificationSettings: {
    events: {
      onVerificationProgress: (event) => {
        console.log(`This request: ${event.txId}`);
      },
    },
  },
});
```

## 遥测

Wayfinder可以为每个请求可选地放出OpenTeleometry跨度. **默认情况下, 遥测被禁用**。您可以通过 `telemetry` 选项.

```typescript
import { createWayfinderClient } from '@ar.io/wayfinder-core';

const wayfinder = createWayfinderClient({
  // other settings...
  telemetrySettings: {
    enabled: true,
    sampleRate: 0.1, // 10% sampling
    exporterUrl: 'https://your-otel-exporter',
    clientName: 'my-app',
    clientVersion: '1.0.0',
  },
});
```

## 复原力

Wayfinder 包括内置的复原功能:

-   **网关重试**:如果网关返回了5xx错误或网络出故障,Wayfinder会自动重新选择不同的网关并重试(最多3个尝试). 客户端错误( 4xx) 立即返回而不重试 .
-   **获取超时**:所有外出请求包括可配置的超时请求——元数据(HEAD,同级列表)为10s,数据检索为30s,以防止被无限期地挂在缓慢或死亡的网关上.
-   **卫生检查网关**数字 : `PingRoutingStrategy` 校验所选网关在通路前响应,如果没有,则用不同的网关重复.
-   **同行列表重试**数字 : `TrustedPeersGatewaysProvider` 当一个网关返回一个空对等列表时,然后响亮地失败而不是默默地不产生任何网关——而默认的提供者倒回了被信任的网关,这样失败会降解出路由而不是阻止.
-   **登记失败是致命的**数字 : `NetworkGatewaysProvider` 重试失败的页面, 一旦重试用完就扔出, 而不是返回部分注册 。 因为 `limit` 在排序后应用,部分读取会返回错误的网关,而不是仅仅减少.
-   **全注册页**数字 : `NetworkGatewaysProvider` 在应用之前先阅读整个链上登记册 `limit`这样 `limit` 选择排名最高的网关, 而不是首先返回的网关。 它在 SDK 最大时页面, 所以这是对当前大小的注册的单一请求 .

## 请求流量

```mermaid
sequenceDiagram
    participant Client
    participant Wayfinder
    participant Gateways Provider
    participant Routing Strategy
    participant Selected Gateway
    participant Verification Strategy
    participant Trusted Gateways

    Client->>Wayfinder: request('ar://example')
    activate Wayfinder

    Wayfinder->>+Gateways Provider: getGateways()
    Gateways Provider-->>-Wayfinder: List of gateway URLs

    Wayfinder->>+Routing Strategy: selectGateway()
    Routing Strategy-->>-Wayfinder: Selected gateway

    Wayfinder->>+Selected Gateway: HTTP request
    Selected Gateway-->>-Wayfinder: Response data

    opt Verification enabled
        Wayfinder->>+Verification Strategy: verifyData()
        Verification Strategy->>Trusted Gateways: Get verification data
        Trusted Gateways-->>Verification Strategy: Verification headers
        Verification Strategy-->>-Wayfinder: Verification result
    end

    Wayfinder-->>Client: Response or error
    deactivate Wayfinder
```

## 常见问题

### @ar\.io/wayfinder-core 是什么？

WayFinder核心库用于智能路由到最佳AR\. IO 网关

### 如何安装 @ar\.io/wayfinder-core？

在项目目录运行 npm install @ar\.io/wayfinder-core，或使用 pnpm add / yarn add / bun add。

### @ar\.io/wayfinder-core 支持 TypeScript 吗？

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

### @ar\.io/wayfinder-core 支持 ESM 还是 CommonJS？

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

### @ar\.io/wayfinder-core 可以商用吗？

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

### @ar\.io/wayfinder-core 的下载量有多少？

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

### @ar\.io/wayfinder-core 还在维护吗？

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