Linera 协议中的以太坊节点访问模块:linera-ethereum 的查询 API、事件解析与测试体系

发布时间:2026/9/10 14:48:20

Linera 协议中的以太坊节点访问模块:linera-ethereum 的查询 API、事件解析与测试体系 Linera 协议中的以太坊节点访问模块linera-ethereum 的查询 API、事件解析与测试体系【免费下载链接】linera-protocolMain repository for the Linera protocol项目地址: https://gitcode.com/GitHub_Trending/li/linera-protocollinera-ethereum是 Linera 协议仓库中专用于访问 Ethereum 区块链节点的 Rust crate在 Cargo.toml 中被描述为 Oracle functionality for Ethereum即以太坊预言机功能。本文将围绕该模块的核心 API、事件解析机制、HTTP 提供者实现、Wasm 环境下的客户端封装以及基于 Anvil 的测试体系展开说明如何在 Linera 智能合约Wasm 应用中查询以太坊状态并给出可直接运行的测试环境搭建方式。模块定位与启用方式从 linera-ethereum/src/lib.rs 可以看到该 crate 的核心职责是provides functionalities for accessing an Ethereum blockchain node提供访问以太坊区块链节点的功能共暴露四个子模块clientRPC 客户端 trait定义查询以太坊节点所需的全部接口common通用数据类型、事件解析辅助函数与错误类型provider仅非 Wasm 目标编译基于 HTTP 的简化 JSON-RPC 提供者test_utils仅非 Wasm 目标编译供测试使用的 Anvil 节点启动器与合约封装。feature 开关ethereum要启用模块的测试能力需要在编译时开启ethereumfeature。这一点在 linera-ethereum/src/lib.rs 与 Cargo.toml 中均有体现[features] ethereum []tests/ethereum_test.rs中所有集成测试都标注了#[cfg(feature ethereum)]因此只有开启该 feature 时测试才会参与编译和执行。docs.rs文档构建也默认启用了ethereumfeature见[package.metadata.docs.rs]。平台相关的依赖裁剪由于linera-ethereum既要服务于原生环境测试、离线工具也要服务于 Wasm32 环境Linera 应用链上运行Cargo.toml 对依赖做了平台区分cfg(target_arch wasm32)下仅引入alloy的rpc-types-eth用于类型定义如Address、U256、Log非 Wasm 环境下引入完整alloyjson-rpc、node-bindings、signer-local、contract等子 feature以及url、tokio用于节点绑定、签名与 HTTP 通信。对应地lib.rs中使用#[cfg(not(target_arch wasm32))]条件导出provider与test_utils两个模块——它们依赖真实网络与本地进程不适合嵌入 Wasm 应用。环境准备安装 Anvil 与 Solc 0.8.25模块文档即 README.md明确指出让测试正常工作需要安装两个外部工具Foundry 工具链中的anvil本地以太坊节点模拟器用于在测试中启动一个即时的 EVM 链Solidity 编译器solc版本 0.8.25用于编译测试合约。其中 solc 0.8.25 与仓库内测试合约的pragma solidity ^0.8.0声明兼容见 simple_token.sol 与 event_numerics.sol。安装完成后运行测试的命令为cargo test -p linera-ethereum --features ethereumget_anvil()位于 test_utils/mod.rs会在测试中自动获取空闲端口并启动一个全新的 Anvil 实例因此无需手动预启动节点pub async fn get_anvil() - anyhow::ResultAnvilTest { let port get_free_port().await?; let anvil_instance Anvil::new().port(port).try_spawn()?; let endpoint anvil_instance.endpoint(); let ethereum_client EthereumClient::new(endpoint)?; let rpc_url Url::parse(endpoint)?; Ok(AnvilTest { anvil_instance, endpoint, ethereum_client, rpc_url }) }核心 API两层 trait 设计模块的查询能力建立在两层抽象之上client.rsJsonRpcClient最底层的 JSON-RPC 传输抽象只负责发请求、收响应EthereumQueries面向业务的高层查询接口把方法名、参数与返回类型编码为具体语义。第一层JsonRpcClient#[async_trait] pub trait JsonRpcClient { type Error: Fromserde_json::Error FromEthereumQueryError; async fn request_inner(self, payload: Vecu8) - ResultVecu8, Self::Error; async fn get_id(self) - u64; async fn requestT, R(self, method: str, params: T) - ResultR, Self::Error where T: Debug Serialize Send Sync, R: DeserializeOwned Send, { /* 默认实现 */ } }request的默认实现完成完整的 JSON-RPC 2.0 封装与校验流程生成自增 id → 构造JsonRpcRequest含jsonrpc: 2.0字段→ 序列化发送 → 反序列化JsonRpcResponse→ 校验返回的id与请求一致、版本号为2.0。任何实现者只需提供request_inner实际的传输逻辑与get_id请求 id 生成策略即可获得类型安全的 RPC 调用能力。第二层EthereumQueriesEthereumQueriestrait 为所有实现了JsonRpcClient的类型提供默认实现blanket impl它定义了七个查询方法全部映射到标准以太坊 JSON-RPC 方法方法底层 RPC语义get_accounts()eth_accounts列出节点管理的所有账户统一转为小写十六进制字符串get_block_number()eth_blockNumber获取最新区块号get_chain_id()eth_chainId获取当前 EVM 链 IDget_balance(address, block_number)eth_getBalance查询指定地址在指定区块高度的余额read_events(contract, event_expanded, from, to)eth_getLogs按过滤器读取合约事件日志non_executive_call(contract, data, from, block)eth_call只读调用合约函数不消耗 gas、不落账is_block_hash_finalized(block_hash)eth_getBlockByHash/eth_getBlockByNumber判断区块哈希是否已 finalize 且处于规范链上这些查询方法均不要求 gas 即可执行在EthereumQueries的文档注释中被明确描述为 do not require gas to be executed因此非常适用于预言机场景Linera 应用可以在不持有任何 ETH 的情况下读取以太坊状态。is_block_hash_finalized 的严谨性client.rs 中is_block_hash_finalized的实现体现了对区块链语义的仔细处理先用eth_getBlockByHash确认区块存在并取得其高度若不存在返回BlockNotFound用eth_getBlockByNumber(finalized)获取最新 finalized 高度若该区块高度超过 finalized 高度则返回false关键的一步由于eth_getBlockByHash会返回 orphan/uncle 区块它们保留原始的非规范高度所以还需用eth_getBlockByNumber(高度)取该高度的规范区块并比较其哈希是否与输入一致。只有完全一致才认定已 finalize 且 canonical。这一实现为桥接类应用判断存款区块是否安全提供了可靠依据。事件读取与解析机制read_events是预言机最常见的调用之一。它的签名要求传入展开式事件签名event name expandedasync fn read_events( self, contract_address: str, event_name_expanded: str, // 例如 Transfer(address indexed,address indexed,uint256) from_block: u64, // 含该块inclusive to_block: u64, // 不含该块exclusive ) - ResultVecEthereumEvent, Self::Error;两点需要特别注意的语义差异client.rs 文档注释中明确说明事件签名必须携带参数类型且 indexed 参数需显式标注写MyEvent(type1 indexed,type2)而不是通常的MyEvent(type1,type2)这样解析器才能区分 topicindexed与 data非 indexed参数区块范围语义与以太坊相反from_block是闭区间含to_block是开区间不含。底层实现会把to_block - 1传给eth_getLogs的 filter。类型系统EthereumDataType事件参数解码后映射为EthereumDataType枚举common.rspub enum EthereumDataType { Address(String), // 十六进制字符串 Uint256(U256), Uint64(u64), Int64(i64), Uint32(u32), Int32(i32), Uint16(u16), Int16(i16), Uint8(u8), Int8(i8), Bool(bool), }支持范围覆盖了 uint/int 的全部分度8/16/32/64/256以及 address、bool足以应对绝大多数 Solidity 事件的参数类型。解析时event_name_from_expanded先把Event(type1 indexed,type2)规约为Event(type1,type2)用于构造eth_getLogs的过滤器parse_log根据每个参数是否以indexed结尾决定数据来源indexed 参数从日志topics中按序读取非 indexed 参数从data中按 32 字节槽位读取common.rs 中topic_index与data_index双游标推进每个 32 字节条目再经parse_entry按目标类型解码bool只接受 0 或 1未知类型返回UnsupportedEthereumTypeError。解析结果EthereumEvent携带values: VecEthereumDataType与block_number: u64事件所在区块号便于上层按区块定位。HTTP 提供者EthereumClientSimplifiedprovider.rs 提供了一个极简的 JSON-RPC over HTTP 实现EthereumClientSimplified只包含两个字段pub struct EthereumClientSimplified { pub url: String, // 以太坊节点 HTTP 端点 pub id: Mutexu64, // 请求 id 计数器从 1 开始 }其request_inner使用reqwest以Content-Type: application/jsonPOST 原始 payload 到节点 URL返回响应字节。get_id通过async_lock::Mutex保证并发安全的自增。这个类型适合在原生非 Wasm环境中直接使用例如测试、离线索引或链下服务。Wasm 环境下的客户端封装JSON Oracle在 Linera 的 Wasm 应用链上智能合约与服务端中不能直接发起 HTTP 请求而是通过 Linera 提供的JSON Oracleperform_http_request间接访问以太坊节点。linera-sdk/src/ethereum.rs 提供了两个对应的客户端ContractEthereumClient用于合约端contract_wit::perform_http_request其get_id恒为 1ServiceEthereumClient用于服务端service_wit::perform_http_request同样get_id恒为 1。两者都实现JsonRpcClient因此自动获得EthereumQueries的全部查询能力。从 ethereum.rs 可以看到它们与linera_ethereum的EthereumQueries、EthereumDataType、EthereumEvent直接打通pub use linera_ethereum::{client::EthereumQueries, common::{EthereumDataType, EthereumEvent}}并且都是 GraphQL scalar可以在服务端 GraphQL 接口中直接序列化/反序列化。这意味着同一套EthereumQueriesAPI 既可以在原生环境EthereumClientSimplified使用也可以在链上 Wasm 合约ContractEthereumClient与服务端ServiceEthereumClient中使用仅传输层不同。实际应用示例linera-bridge/contracts/evm-bridge/src/contract.rs 中的 EVM 桥合约正是这样接入的它导入ethereum::{ContractEthereumClient, EthereumQueries}在合约内读取以太坊存款事件service.rs 则使用ServiceEthereumClient在服务端查询。这构成了 Linera 与以太坊之间双向桥的读取侧基础设施。测试工具与测试用例测试工具集test_utilstest_utils/mod.rs 提供了一套开箱即用的测试基础设施EthereumClient封装了alloy的FillProvider含 Gas、Nonce、ChainId、Wallet 等 filler使用 Anvil 的预置私钥0xac0974...f2ff80作为签名者可发起真实交易AnvilTest一个运行中的 Anvil 实例 连接好的客户端get_address(index)可取 Anvil 预置账户地址SimpleTokenContractFunction部署并封装测试代币合约提供balance_of(address, block)走non_executive_call只读查询与transfer(from, to, value)真实签名交易两个方法EventNumericsContractFunction部署用于全类型事件解析测试的合约。两个测试合约的 Solidity 源码位于 contracts/simple_token.sol含Initial与Transfer(address indexed,address indexed,uint256)事件和 contracts/event_numerics.solTypes事件覆盖 address、uint/int 各分度与 bool。对应的编译产物 ABIJSON保存在contracts/目录下测试运行时通过sol!宏直接加载。关键测试场景ethereum_test.rs 中验证了以下行为测试验证点test_get_chain_idAnvil 默认 chain ID 为 31337test_get_accounts_balanceAnvil 每个预置账户余额均为 10000 ETH10000000000000000000000weitest_event_numerics事件参数按EthereumDataType逐项精确解码含大 uint256、负数 int 与 booltest_simple_token_eventsTransfer事件可被read_events读回indexed 地址从 topic 中解码区块号为 2test_simple_token_queriesnon_executive_call查询历史区块余额转账前 1000/0转账后 990/10test_simple_token_queries还演示了一个实用模式查询历史状态无需等待链上交易——先用签名客户端执行transfer落账再用non_executive_call携带区块号参数eth_call读取任意高度的余额快照这正是预言机做状态见证的基础。小结linera-ethereum是 Linera 协议中以太坊互操作能力的基石它以两层 trait 抽象JsonRpcClientEthereumQueries提供了类型安全的以太坊查询接口以展开式事件签名与EthereumDataType实现了完整的日志解码并通过 JSON Oracle 让同一套 API 在原生、链上合约与服务端三个环境中复用。配合 Anvil 与 solc 0.8.25开发者可以在本地完整复现从读取账户、余额、事件到非执行调用、finality 校验的全流程为构建以太坊桥、跨链预言机等应用打下基础。进一步阅读可参考 linera-sdk/src/ethereum.rsWasm 客户端、evm-bridge实际桥接用法以及 CONTRIBUTING.md参与贡献指引项目整体以 Apache 2.0 协议开源。【免费下载链接】linera-protocolMain repository for the Linera protocol项目地址: https://gitcode.com/GitHub_Trending/li/linera-protocol创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/9/10 14:43:19

Hadoop电影推荐系统:从伪分布式搭建到ALS矩阵分解实战

简介:本资源是一个基于Hadoop分布式框架实现的电影推荐系统完整工程,面向大数据初学者、Java开发人员及推荐系统实践者,解决海量用户行为数据下的个性化推荐建模与并行计算落地问题。压缩包共1117个文件,以379个PHP和169个HTML文件…

2026/9/10 15:43:35

SpringBoot驾校学员管理系统设计与实现

1. 项目概述:SpringBoot驾校学员管理系统设计与实现 去年帮朋友驾校做信息化改造时,发现市面上多数学员管理系统要么功能冗余要么操作复杂。于是基于SpringBoot设计了一套轻量级解决方案,从报名到拿证全流程数字化管理,特别适合中…

2026/9/10 15:43:34

锂枝晶抑制与电池隔膜优化技术解析

1. 锂枝晶生长机制与电池安全痛点锂金属负极因其极高的理论比容量(3860 mAh/g)和最低的电极电位(-3.04 V vs. SHE)被视为下一代高能量密度电池的"圣杯"。但在实际应用中,锂枝晶的生长问题就像一把悬在头顶的…

2026/9/10 15:43:34

PHP协程调度器原理与Swoole高性能实现

1. PHP协程调度器实现原理与核心价值在传统PHP开发中,阻塞式I/O操作一直是性能瓶颈的根源。当我们需要处理高并发请求时,通常会采用多进程或多线程方案,但这会带来显著的内存开销和上下文切换成本。PHP协程调度器的出现,本质上是通…

2026/9/10 15:38:34

龙珠数字藏品与游戏模组的技术实现与市场分析

1. 项目背景解析 "dragonballz_e209-2"这个看似神秘的代号,实际上蕴含着丰富的文化基因和技术内涵。作为一名长期关注二次元文化和技术交叉领域的从业者,我首次看到这个命名时就意识到它可能代表着某种融合了经典动漫元素与现代技术理念的创新…

2026/9/9 13:11:35

超人会飞不算本事:系统稳定依赖清晰规则与边界设计

开头先不绕弯子。“#斯坦李吐槽dc 所以超人是无缘无故会飞的嘛哈哈哈哈哈哈哈锤哥真是技术人才啊!#雷神 #复联”这类调侃式短标题,第一波冲击力在于它把两个宇宙的角色塞进同一个吐槽箱里,但细想一下就能发现,它真正碰到的根本不是…

2026/9/10 11:16:38

超人VS蜘蛛侠:拆解超级IP的影响力与传播方法论

把“蜘蛛侠 vs 超人”放在 CSDN 上聊,可能很多人第一反应是走错片场了。但如果把这两个角色看成“两个持续运营了 80 多年的文化产品”,你会发现,这场比较本质上是两个不同 IP 策略的长期结果对比:超人赢在定义了整个超级英雄题材…

2026/9/9 16:31:09

基于CNN的调制信号识别:MATLAB实现时频图分类实战

简介:本资源是一套面向通信工程与信号处理方向学习者、研究者的深度学习实践方案,聚焦调制信号自动检测与识别这一典型无线通信任务,解决传统方法依赖人工特征、低信噪比下性能下降等痛点。压缩包共12个文件(10.73MB)&…

2026/9/10 0:00:55

目录对比去重实战:用哈希算法精准清理重复文件

我电脑里现在还有一块换了三次机的“数据墓地”硬盘,里面存着2016年以前所有旧笔记本的完整备份。平时不觉得有什么,直到前阵子想把它整理归档,发现同一个安装包、同一批照片、同一份论文草稿,在几个不同的备份目录里反复出现。更…

2026/9/10 0:00:55

Leaflet离线地图完整Demo合集:内网部署与坐标纠偏实战

简介:这是一份面向Web GIS开发者的LeafLet离线地图示例合集,帮助开发者快速掌握离线地图从搭建到交互的完整流程。压缩包共723个文件,大小14.06MB,以319个js脚本、175个html页面和29个css样式文件为主体,配合png/svg图…

2026/9/10 0:00:55

MATLAB读取Rinex 3.02观测文件:多系统GNSS数据解析实战

简介:基于MATLAB开发的Rinex3.02版观测文件(o文件)读取代码包,面向卫星定位导航方向的学习者与研究人员,用于解决新版观测文件的数据解析、历元提取与时间转换问题。压缩包共4个文件,包含两个m脚本、一个19…

2026/9/10 12:32:02

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/10 15:19:50

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/9 10:21:54

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码