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

发布时间:2026/10/29 13:22:50

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/10/28 15:22:30

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

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

2026/10/29 13:21:05

绕开DeepSeek官网排队:硅基流动托管推理接入实战

简介:这份文档面向希望稳定使用 DeepSeek、又不想被官网“服务器繁忙”提示打断的 AI 使用者与开发者,围绕借助硅基流动平台调用 DeepSeek 满血版这一思路展开,兼顾本地部署吃配置、高并发请求受限等实际痛点,适合入门到进阶的模型…

2026/10/29 13:21:05

计算机专业转型网络安全:职业路径与技术栈解析

1. 计算机专业毕业生的职业迷思与现状 2008年我刚从某高校计算机系毕业时,班里90%的同学都直奔互联网大厂的开发岗位,仿佛写代码是计算机专业唯一的出路。十几年后的今天,当我以网络安全工程师的身份回看这段经历,发现这个行业正在…

2026/10/29 13:21:05

AI Agent开发中的三大工程挑战与解决方案

1. Agent工程中的核心痛点解析在AI Agent开发领域,数据清洗、权限开通和接口稳定性这三个问题被从业者戏称为"三大脏活累活"。这些工作看似基础,却消耗了开发团队近60%的工程时间。以金融领域的智能客服Agent为例,数据清洗可能涉及…

2026/10/29 13:21:05

智能体(Agent)与工作流系统的核心差异与技术实现

1. 概念辨析:Agent与工作流的本质差异最近AI领域涌现出大量打着"Agent"旗号的产品和框架,但仔细观察就会发现,其中很多本质上只是传统工作流系统的变种。要识别真正的智能体(Agent),我们需要先明…

2026/10/29 13:21:05

技能不是关键词堆砌:从深度拆解到技能栈组合与迁移

1. 先分清技能、经验、工具名:很多人把简历写成了购物清单 我这些年看过上千份简历、做过几十次面试,也带过不少新人,发现一个特别普遍的问题:大家一说"skills",第一反应就是往简历上堆关键词——Vue、React…

2026/10/29 13:16:04

影刀RPA实战:职场效率提升与自动化创收指南

1. 项目概述:当RPA遇上职场效率革命 那天晚上9点半,我盯着电脑屏幕上一排未处理的Excel表格,突然意识到自己正在重复第37次"复制-粘贴-校验"的操作。就在这个瞬间,我决定让影刀RPA这个数字员工接手这些机械劳动。经过一…

2026/10/28 14:42:12

全国计算机二级C语言真题PDF高效刷题指南

简介:这份PDF是全国计算机二级C语言考试的试题与答案解析,专为备考二级C语言的考生准备。内容涵盖C语言特点与设计理念、程序基本组成单位、main函数执行流程、函数嵌套调用规则、标识符命名规范、整型实型字符型数据类型、八进制十六进制数合法形式、运…

2026/10/28 15:28:56

requests+BeautifulSoup:爬虫抓取h1标题的入门实战指南

简介:一份以实战为导向的Python爬虫入门资源,面向具备基本编程基础、希望快速掌握网络数据抓取的初学者,可解决从零编写简单爬虫的常见困惑。实例以requests库发送HTTP请求、BeautifulSoup解析HTML文档,完整演示从网页中提取 标题…

2026/10/28 3:32:29

递推最小二乘参数辨识MATLAB编程:二阶系统与渐消记忆实现

简介:这是一篇面向控制系统、信号处理与机器学习等领域学习者的最小二乘参数辨识程序说明文档。资源共包含一个docx格式文档,压缩包大小七十八KB,内容围绕递推最小二乘算法和渐消记忆最小二乘算法展开:先构造一个极点位于单位圆内…

2026/10/29 0:03:42

学生选课系统DFD图绘制指南:边界划分与分层校验实战

简介:文档以顶层与第一层DFD图为核心,完整刻画学生选课系统的逻辑模型,面向软件工程课程设计、系统分析学习及毕设前期建模人群。顶层图界定系统边界,外部实体包括管理员、教师和学生三类角色;第一层图进一步细化用户登…

2026/10/29 0:03:42

JIRA敏捷落地:Scrum角色权限、Sprint与燃尽图避坑指南

简介:围绕“基于JIRA的敏捷开发项目管理”这一主题,面向产品负责人、Scrum Master及研发测试成员,梳理Scrum角色分工、迭代流程与JIRA工具配置的对应关系,适合初、中级团队导入敏捷管理时参考。压缩包共1个docx文件,大…

2026/10/29 0:03:42

SEMI S8人机工程验收实战:从条款拆解到现场实测的完整指南

简介:面向半导体设备设计、制造与运维工程师及安全合规人员,这份资料聚焦SEMI标准体系下的设备安全规范,重点收录SEMI S8-0308《半导体制造设备人体工程学工程安全指南》。内容围绕设备设计原则、错误与事故预防、人体工程学适配三大主线展开…

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

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

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