客户端接口是外部应用程序与 Fuel Core 节点交互的主要网关。它围绕全面的 GraphQL API 构建，为查询区块链数据、提交交易和监控系统状态提供统一的接口。该接口包括服务器端 GraphQL API 实现和适用于 Rust 应用程序的 FuelClient SDK。
GraphQL API 在 /v1/graphql (HTTP) 和 /v1/graphql-sub (WebSocket 订阅) 公开，为所有区块链操作提供查询、变更和实时订阅。
有关节点间网络通信的信息，请参阅网络。
Fuel Core 提供了全面的 GraphQL API，作为客户端应用程序的主要接口。此 API 允许客户端执行以下操作：
GraphQL API 通过 HTTP/HTTPS（用于查询和变更）和 WebSocket（用于订阅）分别在 /v1/graphql 和 /v1/graphql-sub 端点公开。
客户端接口架构概述
来源
GraphQL 模式在 schema.sdl 中定义，并在多个解析器模块中实现。该模式遵循标准的 GraphQL 约定，包含根 Query、Mutation 和 Subscription 类型。
GraphQL 模式类型系统
Query 类型提供对区块链数据的只读访问
| 操作 | 描述 | 实现 |
|---|---|---|
transaction(id: TransactionId!) | 获取单个交易 | TxQuery |
transactions(first, after, last, before) | 分页交易 | TxQuery |
block(id: BlockId, height: U32) | 按 ID 或高度获取区块 | BlockQuery |
balance(owner: Address!, assetId: AssetId!) | 获取账户余额 | BalanceQuery |
coins(filter: CoinFilterInput!) | 获取账户的 UTXO | CoinQuery |
dryRun(txs: [HexString!]!) | 模拟交易执行 | TxQuery |
assembleTx(...) | 自动组装交易输入 | TxQuery |
chain() | 获取链元数据 | ChainQuery |
Mutation 类型支持状态更改操作
| 操作 | 描述 | 实现 |
|---|---|---|
submit(tx: HexString!) | 提交交易至交易池 | TxMutation |
produceBlocks(blocksToProduce: U32!) | 手动生成区块 | BlockMutation |
Subscription 类型提供实时数据流
| 操作 | 描述 | 实现 |
|---|---|---|
statusChange(id: TransactionId!) | 交易状态更新 | TxStatusSubscription |
submitAndAwait(tx: HexString!) | 提交并等待完成 | TxStatusSubscription |
来源
FuelClient 结构体提供了一个 Rust 接口，用于与 GraphQL API 交互，处理 HTTP/WebSocket 连接、请求序列化和响应解析。
FuelClient 架构
客户端支持多种初始化方法
| 方法 | GraphQL 操作 | 返回类型 |
|---|---|---|
health() | health 查询 | 布尔值 |
submit(tx) | submit 变更 | TransactionId |
dry_run(txs) | dryRun 查询 | Vec<TransactionExecutionStatus> |
transaction(id) | transaction 查询 | Option<Transaction> |
chain_info() | chain 查询 | ChainInfo |
balance(owner, asset_id) | balance 查询 | 余额 |
assemble_tx(...) | assembleTx 查询 | AssembleTransactionResult |
estimate_predicates(tx) | estimatePredicates 查询 | Transaction |
ConsistencyPolicy 确保查询针对一致的区块链状态执行
用途
为了实现实时更新，客户端通过 Server-Sent Events 支持 GraphQL 订阅
来源
客户端接口的主要功能之一是处理交易提交和状态跟踪。让我们来审视一下交易流程
交易提交和状态流程
TransactionStatus 联合类型表示交易所有可能的状态
交易状态机
| 状态类型 | 模式定义 | 描述 |
|---|---|---|
SubmittedStatus | 第 329-331 行 | 交易已进入交易池 |
SuccessStatus | 第 372-382 行 | 在区块中成功执行 |
FailureStatus | 第 370-382 行 | 执行失败并附带原因 |
SqueezedOutStatus | 第 301-304 行 | 从交易池中移除，未执行 |
PreconfirmationSuccessStatus | 第 912-920 行 | 预演验证通过 |
PreconfirmationFailureStatus | 第 901-910 行 | 预演验证失败 |
状态实现
来源
API 允许客户端对交易执行“预演”，而无需将其提交到区块链
在 SDK 中
API 可以根据高级要求自动组装具有正确输入和输出的交易
在 SDK 中
此功能通过自动处理硬币选择和费用计算来简化客户端交易构建。
API 通过 GraphQL 订阅支持实时交易状态更新
在 SDK 中
来源
客户端接口使用端口和适配器六边形架构，以将 GraphQL API 与核心服务解耦
端口和适配器架构
| 端口 | 目的 | 关键方法 |
|---|---|---|
TxPoolPort | 交易池操作 | transaction()、insert()、latest_pool_stats() |
BlockProducerPort | 区块执行和预演 | dry_run_txs()、storage_read_replay() |
TxStatusManager | 交易状态跟踪 | status()、tx_update_subscribe() |
OnChainDatabase | 共识数据访问 | transaction()、block()、latest_height() |
OffChainDatabase | 索引数据访问 | tx_status()、balance()、owned_coins_ids() |
这种架构支持依赖注入、可测试性以及 GraphQL 层与业务逻辑之间的清晰分离。
来源
GraphQL API 通过具有专用存储层的双数据库架构访问数据
数据库层架构
| 层 | 数据类型 | 关键表 |
|---|---|---|
| 链上 | 共识关键数据 | FuelBlocks、Transactions、Coins、Messages、ContractsRawCode |
| 链下 | 索引和派生数据 | TransactionStatuses、OwnedCoins、CoinBalances、OwnedTransactions |
链上操作
链下操作
这种分离确保了高效查询，同时维护了共识完整性。
来源
客户端接口在多个层级实现了全面的错误处理
错误流架构
FuelClient SDK 错误
模式转换错误
async_graphql::Error 传播TransactionStatus::Failure 返回client::Error::Other 中ConversionError 变体失败的交易包含全面的错误信息
这种分层方法确保错误得到正确分类并包含足够的上下文信息以进行调试。
来源
客户端接口为应用程序与 Fuel Core 节点交互提供了全面而灵活的方式。通过其 GraphQL API 和 FuelClient SDK，它处理了客户端与节点交互的所有方面，从数据查询到交易提交和状态跟踪。
模块化架构以及清晰定义的端口和适配器确保了关注点的明确分离，使系统易于维护和扩展。