data

用途

本技能用于读取 Stellar 链上状态，提供两种 API 范式：Stellar RPC（首选，面向智能合约、实时状态与新项目）和 Horizon（偏传统，面向历史数据与遗留应用）。官方建议所有新项目使用 Stellar RPC，Horizon 主要用于历史查询和遗留兼容路径。

主要能力

Stellar RPC 支持以下方法：

getAccount：返回账户及用于构建交易的序列号。
getHealth：返回健康状态，如 { status: "healthy" }。
getLatestLedger：返回最新账本信息，如 { id, sequence, protocolVersion }。
getLedgerEntries：读取合约存储。
simulateTransaction：模拟交易，可判断模拟失败或成功并查看成本与结果。
sendTransaction：发送已签名交易，返回 PENDING 后可轮询 getTransaction 获取结果。
getTransaction：返回状态（SUCCESS / FAILED / NOT_FOUND）、returnValue（合约调用）与 ledger。
getEvents：按起始账本与过滤器（类型、合约 ID、主题）获取事件。

Horizon 支持账户、交易、操作、效果、账本等 REST 端点，并支持原生流式订阅与分页。

使用方式

RPC 端点：

Mainnet：由所选提供商提供（见 RPC providers directory）。
Testnet：https://soroban-testnet.stellar.org
Futurenet：https://rpc-futurenet.stellar.org
Local：http://localhost:8000/soroban/rpc

初始化示例：

import * as StellarSdk from "@stellar/stellar-sdk";
const rpc = new StellarSdk.rpc.Server("https://soroban-testnet.stellar.org");

读取合约存储示例：

const key = StellarSdk.xdr.LedgerKey.contractData(
  new StellarSdk.xdr.LedgerKeyContractData({
    contract: new StellarSdk.Address(contractId).toScAddress(),
    key: StellarSdk.xdr.ScVal.scvSymbol("Counter"),
    durability: StellarSdk.xdr.ContractDataDurability.persistent(),
  })
);
const entries = await rpc.getLedgerEntries(key);

发送交易并轮询结果：

const response = await rpc.sendTransaction(signedTransaction);
if (response.status === "PENDING") {
  let result = await rpc.getTransaction(response.hash);
  while (result.status === "NOT_FOUND") {
    await new Promise(r => setTimeout(r, 1000));
    result = await rpc.getTransaction(response.hash);
  }
}

获取事件示例：

const events = await rpc.getEvents({
  startLedger: 1000000,
  filters: [
    {
      type: "contract",
      contractIds: [contractId],
      topics: [["*", StellarSdk.xdr.ScVal.scvSymbol("transfer").toXDR("base64")]],
    },
  ],
});

网络配置采用按网络惰性工厂，示例文件 lib/stellar-config.ts 中定义 mainnet、testnet、local 三套配置，通过 STELLAR_NETWORK 环境变量选择，并导出 rpc 与 horizon 实例。

适用场景

调用 Stellar RPC 方法（getLatestLedger、getLedgerEntries、getEvents、simulateTransaction、sendTransaction）。
查询 Horizon 端点（accounts、transactions、operations、effects、ledgers）。
流式订阅实时事件或操作。
拉取超出 RPC 约 7 天窗口的历史数据（Hubble、Galexie）。
为特定工作流在 RPC 与 Horizon 之间做选择。

相关技能：构建待发送交易见 ../dapp/SKILL.md；智能合约模拟与事件发射见 ../smart-contracts/SKILL.md；资产余额与信任线查询见 ../assets/SKILL.md；标准（SEP-7 深链、SEP-10 认证）见 ../standards/SKILL.md。

限制

历史窗口：多数 RPC 方法（getTransaction、getEvents 等）仅覆盖近期数据，约 7 天。
getLedgers 例外：在数据湖支持的提供商上，“Infinite Scroll”可翻页至该提供商数据湖所及范围（可能到创世）；普通 RPC 实例受 getHealth().oldestLedger 限制，更早请求会以 -32600 失败。使用前需先检查深度。
无流式：RPC 不支持 WebSocket，需轮询更新。
偏合约：对经典 Stellar 数据支持有限。

历史数据访问

超出 RPC 保留窗口（约 7 天）的数据可通过：

Hubble（BigQuery）：如查询 crypto-stellar.crypto_stellar.history_transactions。
Galexie：自托管数据处理管道，https://github.com/stellar/galexie。
数据湖：RPC “Infinite Scroll” 由 Stellar 数据湖（SEP-0054 格式的云对象存储）驱动。公开访问：s3://aws-public-blockchain/v1.1/stellar/ledgers/pubnet（AWS Open Data）。自托管可用 Galexie 导出至 AWS S3 或 Google Cloud Storage。托管：Quasar（Lightsail Network）提供托管 Galexie 数据湖与 Archive RPC 端点。规模约 3.8TB，年增约 0.5TB；自托管成本约 $160/月（$60 计算 + $100 存储）。文档：https://developers.stellar.org/docs/data/apis/rpc/admin-guide/data-lake-integration

第三方索引器：Mercury（https://mercurydata.app）、SubQuery（https://subquery.network）、Goldsky（https://goldsky.com）、StellarExpert API（https://stellar.expert/openapi.html）。完整索引器目录：https://developers.stellar.org/docs/data/indexers

最佳实践

使用 RPC：新应用开发、智能合约交互、交易模拟与提交、实时账户状态。使用 Horizon：历史交易查询、支付流式订阅、遗留应用维护、丰富账户元数据。

错误处理：RPC 错误可按 code 判断（如 400 无效交易、503 服务不可用）；Horizon 错误可从 error.response?.data?.extras.result_codes 读取交易与操作的详细错误码。

限流：RPC 与 Horizon 均有速率限制，建议使用指数退避重试、适当缓存响应，高流量应用可考虑自建节点。