Colibri 无国籍者 — JavaScript / TypeScript
以加密方式验证Ethereum RPC数据——不运行一个完整的节点.
Colibri 无国籍者是Ethereum的高度高效的证明人/验证人(即将对Layer-2s如OP-Stack的支持). 此软件包在浏览器中以 Web Assembly 和 a 运行 C 核心 在节点.js的本地加通 (自动WASM倒置) EIP-1193 (英语) 提供者接口——因此它会直落到醚,web3.js,或viem上,同时加密地验证每个响应.
网站 • 妇女 文档 • 妇女 白皮书 • 妇女 隐私( PAP)
为什么是Colibri?
- 无国籍人 ——核查只需要证明和被核对的同步委员会. 同步委员会是本地缓存的,所以它不必随每个请求一起出行,但是它和空缓存一样有效,或者根本没有. 没有持续状态,没有逐个块头处理,没有完整的节点.
- 经加密核实的RPC ——证明人为RPC响应的有效性创造出证明;核查人对照BLS签名进行核查.
- 离线核查 ——一个证明是完全自成一体的,可以在没有任何网络连接的情况下进行验证,多亏了zk-crew为同步委员会和已签字的检查站.
- 点播,不总是 - Colibri只有在你提出要求时才起作用。 它不会在背景中持续同步,所以在您的应用程序闲置时它不会燃烧带宽,CPU,或电池.
- 核实历史数据(比 ~27h / 8192 个区块旧) - 使用
historical_summaries来自信标状态的默克勒证明,Colibri清空地验证了其他轻客户完全失败的旧交易和收据. eth_getLogs完整性证明 ——密码学保证,对于请求的块范围,没有省略匹配事件(opt-in通过logs_completeness) (中文(简体) ).- 完全核实的本地交易模拟 ——对照已核实状态模拟交易 签署前,因此用户可以准确地显示交易将做什么.
- 小快( F) 大部分请求都比普通的RPC呼叫要慢得多 基准。 。 。 .
- 节点.js的原生速度 ——捆绑有平台优化的N-API预建 弹出 组装使验证~25-30x比WASM快;不支持的平台透明地倒回WASM.
- 隐私意识 ——实用适应隐私(PAP)模式. 见 隐私白皮书。 。 。 .
安装
npm install @corpus-core/colibri-stateless
进口/使用(ESM和通用JS)
Colibri作为出版物出版 双套件 并可在无害环境管理和共同联合体系环境中使用.
无害环境管理(浏览器、现代捆绑器、节点无害环境管理)
import Colibri, { Strategy, set_wasm_url } from "@corpus-core/colibri-stateless";
// Optional: only needed if you want to pin the WASM location explicitly
// set_wasm_url("https://example.com/c4w.wasm");
const client = new Colibri();
通用JS(如:Jest,更古老的节点工具链)
const { default: Colibri, Strategy, set_wasm_url } = require("@corpus-core/colibri-stateless");
// Optional: in Node you can explicitly point to the wasm file path
// set_wasm_url(require("node:path").join(__dirname, "c4w.wasm"));
const client = new Colibri();
节点的本地Addon
在Node.js中,包会自动加载一个被预建的本地加通(N-API)来代替WASM构建. 它静态地将C核心与平台优化连接 弹出 组装,使BLS配对——验证的主要成本—— ~25-30x 较快。不需要修改代码或可选的依赖关系;浏览器捆绑不受影响.
预建为 linux-x64, (中文(简体) ), linux-arm64, (中文(简体) ), darwin-arm64, (中文(简体) ), darwin-x64 财务报告和审定财务报表 win32-x64。在任何其他平台上(或在装载失败的情况下),客户端透明地回归到WASM.
import { getRuntime } from "@corpus-core/colibri-stateless";
console.log((await getRuntime()).kind); // 'native' or 'wasm'
覆盖 : C4_DISABLE_NATIVE=1 (总是WASM), C4_FORCE_NATIVE=1 (失败而不是倒下), C4_NATIVE_ADDON=<path> (解释外加道. 见 文档 详细信息以及来自源代码的构建指令.
使用 Colibri 作为 RPC 提供者
Colibri Class执行EIP-1193接口,因此任何支持EIP-1193提供者的库都可以轻松地将Colibri用作RPCProvider.
目前订阅和过滤器尚未执行,所以如果您需要这些功能,则强制使用不同的提供者来完成这些任务,并使用Colibri验证所找到的日志。 但是,这些特点将在下一期中实施.
以太Js 6.x (英语)
import { BrowserProvider } from "ethers";
import Colibri from "@corpus-core/colibri-stateless";
async function main() {
// Initialize the client with the default configuration and RPCs
const client = new Colibri({prover:['https://mainnet.colibri-proof.tech']});
// Use Colibri client as the EIP-1193 provider for ethers (v6)
const provider = new BrowserProvider(client);
// Fetch the latest block using the ethers provider
const block = await provider.getBlock('latest');
console.log("Block fetched via ethers:", block);
}
main().catch(console.error);
以太Js 5.x (英语)
import * as ethers from "ethers";
import Colibri from "@corpus-core/colibri-stateless";
async function main() {
// Initialize the client with the default configuration and RPCs
const client = new Colibri({prover:['https://mainnet.colibri-proof.tech']});
// Use Colibri client as the EIP-1193 provider for ethers (v6)
const provider = new ethers.providers.Web3Provider(client);
// Fetch the latest block using the ethers provider
const block = await provider.getBlock('latest');
console.log("Block fetched via ethers:", block);
}
main().catch(console.error);
网络3.js
import Web3 from 'web3';
import Colibri from "@corpus-core/colibri-stateless";
async function main() {
// Initialize the client with the default configuration and RPCs
const client = new Colibri({prover:['https://mainnet.colibri-proof.tech']});
// Use Colibri client as the EIP-1193 provider for web3.js
const web3 = new Web3(client);
// Fetch the latest block using the web3.js provider
const block = await web3.eth.getBlock('latest');
console.log("Block fetched via web3.js:", block);
}
main().catch(console.error);
维埃姆
import { createPublicClient, custom } from 'viem';
import { mainnet } from 'viem/chains';
import Colibri from "@corpus-core/colibri-stateless";
async function main() {
// Initialize the Colibri client
const colibriClient = new Colibri({prover:['https://mainnet.colibri-proof.tech']});
// Create a viem Public Client using Colibri as a custom EIP-1193 transport
const viemClient = createPublicClient({
chain: mainnet, // Specify the chain
transport: custom(colibriClient) // Wrap Colibri client
});
// Fetch the latest block using the viem client
const block = await viemClient.getBlock({ blockTag: 'latest' });
console.log("Block fetched via viem:", block);
}
main().catch(console.error);
安全交易核查
保护你的DApp免受国家预防机制供应链攻击和交易操纵:
import { BrowserProvider } from "ethers";
import Colibri from "@corpus-core/colibri-stateless";
// Secure transactions with built-in verification
const client = new Colibri({
fallback_provider: window.ethereum, // MetaMask as Signer
verifyTransactions: true // Prevents transaction manipulation
});
const provider = new BrowserProvider(client);
// Send transaction - automatically verified before broadcast
const tx = await provider.getSigner().sendTransaction({
to: "0x742d35cc6633C0532925a3b8D8C9C4e2F9",
value: "0x16345785d8a0000", // 0.1 ETH
gasLimit: "0x5208"
});
console.log("Verified transaction:", tx.hash);
你应用软件里有建筑证明.
不想使用远程服务构建证明的,也可以直接使用Colibri构建证明或验证. 一个证明就是Juzst一个UInt8箭头或只是字节. 在申请中将其写入文件或包装,并随时核实:
import Colibri from "@corpus-core/colibri-stateless";
async function main() {
const method = "eth_getTransactionByHash";
const args = ['0x2af8e0202a3d4887781b4da03e6238f49f3a176835bc8c98525768d43af4aa24'];
// Initialize the client with the default configuration and RPCs
const client = new Colibri();
// Create a proof for the given method and arguments as UInt8Array
const proof = await client.createProof(method, args);
// Verify the proof against requested method and arguments
const result = await client.verifyProof(method, args, proof);
// the result will be the expected json
console.log(result);
}
main().then(console.log).catch(console.error);
配置
Colibri客户端的构建者接受一个配置对象,这个对象可能配置客户端. 接受下列参数:
-
chainId- 要使用的链条( 默认为 1, whoich 是主网) .new Colibri({ chainId: 0x7}) -
beacon_apis- 信标的阿皮斯
使用官方访问信标链的一系列端点 灯塔节点API。矩阵可能包含一个以上的url,如果一个API没有响应下一个 URL 将起到倒置的作用。 此信标 API 在直接或即使您正在使用远程验证器时, 也会直接从信标 API 中获取 eitehr .new Colibri({ beacon_apis: [ 'https://lodestar-mainnet.chainsafe.io' ]}) -
checkpointz- 用于检查站服务器(检查点或灯塔API)
一系列服务器端点,用于获取最终确定的检查点数据和薄弱的主观性验证. 支持专用的Checkpointz服务器和标准Beacon API节点,因为核查员使用Beacon-API兼容的端点/eth/v1/beacon/states/head/finality_checkpoints这些服务器提供了用于安全初始化和定期验证的已敲定信标块根。 多个URL允许自动回落. 主网的公用Checkpointz服务器默认,但您也可以使用自己的灯塔节点实现最大信任.// Using public Checkpointz servers (default) new Colibri({ checkpointz: [ 'https://sync-mainnet.beaconcha.in', 'https://beaconstate.info' ]}) // Or using your own Beacon node new Colibri({ checkpointz: [ 'http://localhost:5052' ]}) -
rpcs- 执行者RPC
用于访问执行层的一系列 rpc 端点。 如果您正在使用远程验证器, 您可能不需要它 。 但本地创建您的证据需要访问执行层的数据 。 拥有一个以上的 rpc- url 允许在无法使用时使用后退 .new Colibri({ beacon_apis: [ "https://nameless-sly-reel.quiknode.pro/<APIKEY>/", "https://eth-mainnet.g.alchemy.com/v2/<APIKEY>", "https://rpc.ankr.com/eth/<APIKEY>" ]}) -
prover- 远程验证器的urls 用于远程验证的端点数组。 这允许在后端生成证明,其中缓存可以加速进程.new Colibri({ prover: ["https://mainnet.colibri-proof.tech" ]}) -
prover_mode- 证明生成模式(默认 ):"remote"如果配置了验证器 URL, 否则"local"(中文(简体) ) 控制如何建立和验证证据。 有五个模式:"local"- 证据完全建立在客户身上。 需要访问灯塔 API 和执行层 RPC 。 完全不信任,但速度较慢,需要更多的基础设施."remote"- 从远程 Colibri 验证服务器获取证据。 最快速的选项, 但依赖于验证服务器来生成验证 。 核查员仍然通过密码检查所有证据."hybrid"-- 共识层的证明(BlockheaderProof)来自Colibri服务器,而执行层的数据(账户证明,存储等)则直接取自RPC提供者. 性能和可缩放性的最佳平衡——Colibri服务器只提供轻量级,可缓存头部的证明,而重的RPC负载则由您现有的提供者承担. 授权eth_getBlockHeader编号 :eth_getBlockByNumber请求以 方便缓存获取请求 (单位:千美元)GET /proof/<method>/<block>/<version>/<zk>/<c4>带有Cache-Control新鲜度绑定,因此在证明器前的CDN可以吸收重复对同个头的要求(每12s只有~1个新块)."proxy"- 和远程一样,但客户端将自己的RPC和Beacon API URL发送到验证服务器. 服务器使用这些端点而不是自己的端点. 当客户端可以访问私人或高价RPC供应商时有用."light_client"- 如混血儿,额外的背景民意调查 块头保持缓存的温暖。 打电话startLightClient()编号 :stopLightClient()来控制投票 默认间隔:12000ms. 默认情况下只有紧凑eth_getBlockHeader已获取; 通过fullBlock: true以获取完整块( 当多块时有用)eth_getTransactionByHash编号 :eth_getTransactionReceipt电话跟随.
// Explicit hybrid mode new Colibri({ prover: ["https://mainnet.colibri-proof.tech"], rpcs: ["https://eth-mainnet.g.alchemy.com/v2/<APIKEY>"], prover_mode: "hybrid" }) // Light client mode const client = new Colibri({ prover: ["https://mainnet.colibri-proof.tech"], rpcs: ["https://eth-mainnet.g.alchemy.com/v2/<APIKEY>"], prover_mode: "light_client" }); client.startLightClient(); // polls eth_getBlockHeader every 12s client.startLightClient(12000, true); // or fetch the full block -
zk_proof- 使用远程 ZK 同步证明拖曳( 默认 ):false(中文(简体) ) 若为true,验证者将使用 ZK 证明拖曳初始同步委员会(ZKSyncData) 由远程验证器提供,而不是通过checkpointz/信任的检查站.new Colibri({ prover: ["https://mainnet.colibri-proof.tech"], zk_proof: true }) -
checkpoint_witness_keys- 使用时的可选检查站签名地址zk_proof(默认 :null(中文(简体) ) 一份Ethereum地址列表(每个20字节). 当前格式是多个地址的单一十六进制字符串 缩合 (无分相.示例(一个签名人,实体核心):
new Colibri({ prover: ["https://mainnet.colibri-proof.tech"], zk_proof: true, checkpoint_witness_keys: "0x07f50c1d17cb84a656692ddfd577c09756cb305b" })示例( 两个签名符):
new Colibri({ zk_proof: true, checkpoint_witness_keys: "0x<addr1_40hex><addr2_40hex>" }) -
trusted_checkpoint- 可选信标块散列用作可信任锚
此单块块将用作锁定器, 为同步委员会获取密钥 。 而不是从起源开始,你可以定义一个开始的块, 在那里你知道块。 如果没有设置可信赖的检查点,核查者将自动从Checkpointz服务器上取取最新完成的检查点,使初始化安全并方便. 建议设立明确信任的检查站,以进行最大限度的安全管制,但不再需要.new Colibri({ trusted_checkpoint: "0x4232db57354ddacec40adda0a502f7732ede19ba0687482a1e15ad20e5e7d1e7" }) -
cache- 用于 rpc 请求的缓存程序
您可以提供自己的执行来缓存 JSON-RPC 请求。 在发出请求之前将使用这些功能,同时也允许模拟处理器缓存对测试的答复.new Colibri({ cache: { cacheable(req: DataRequest) { return req.payload && req.payload.method!='eth_blockNumber' }, get(req: DataRequest) { try { return fs.readFileSync(`${cache_dir}/${req.url}`); } catch (e) { return null } }, set(req: DataRequest, data: Uint8Array) { fs.writeFileSync(`${cache_dir}/${req.url}`, data); } }}) -
debug- 如果真实, 您将在控制台上看到调试输出new Colibri({ debug: true}) -
include_code- 如果合同的代码属实,则在创建证据时将包含该代码。 这只有在为 eth call 创建自己的证明时才有意义。 (默认:虚假)new Colibri({ include_code: true}) -
use_accesslist- 狦true(默认),本地eth_call编号 :eth_estimateGas编号 :colibri_simulateTransaction证据的使用eth_createAccessList发现触摸过的账户和存储。 设定为false只选择继承遗产debug_traceCall(预设追踪器)路径C4_PROVER_FLAG_USE_DEBUG_TRACE),该API并不在每个 RPC 供应商上提供,而合同代码通常无论如何都会被缓存. 当从一个已经选择了自己路径的远程验证器中获取证据时不相关 .new Colibri({ use_accesslist: true }) // default new Colibri({ use_accesslist: false }) // legacy debug_traceCall -
logs_completeness- 如果是真的的话,eth_getLogs生产(证明)和要求(核查)a 完整性证明 超过请求的块范围[fromBlock, toBlock]。它证明没有省略匹配日志,而不仅仅是返回的日志是有效的。 此设置了校正旗 (S)1 << 12)和核查旗帜(1 << 9),并需要一个支持它的证明. 范围结束toBlock可以是被钉住的块块散列/数目,或"latest"· ;"safe"编号 :"finalized"尚未支持。 (默认: 虚假, 音轨问题 # 128)new Colibri({ logs_completeness: true }) -
privacy_mode- 说吧 PAP( 实用适应隐私) 模式 :"none"(违约)或"basic"与"basic",验证人可以使用缓存存储来进行乐观执行并随后进行验证;方法类型可以依赖于参数. 这个特征仍然是实验性的!new Colibri({ privacy_mode: "basic" }) -
oblivious_nodes- 私人TEE RPC终点eth_getProof(默认: 为空). 设定VERIFY_FLAG_OBLIVIOUS财务报告和审定财务报表 行动计划 自动。 为了保护隐私eth_call,同时使用privacy_mode: "basic"(或依赖自动APP在被遗忘时),prover_mode: "hybrid",并忽略了节点——见下文.// Privacy-preserving eth_call (https://rpc.safe-node.com/ needs an API key for testing) new Colibri({ privacy_mode: "basic", prover_mode: "hybrid", oblivious_nodes: ["https://rpc.safe-node.com/"], })为什么:
hybrid仅从验证器获取块证明;存储值来自 RPC/禁用节点,并在当地验证.basic(PAP) 避免eth_createAccessList(将泄露意图); EVM 乐观地发现存储eth_getProof请求离开客户.TEE/ORAM详细信息: 盲目实验室。 。 。 .
-
verify- 决定哪些请求应予核实,哪些请求应从默认RPC-提供人处获取。 它允许您加速执行不关键的请求 .new Colibri({ verify: (method, args) => method != 'eth_blockNumber' }) -
proofStrategy- 用于确定如何处理证据的战略功能。 目前有3个默认执行.Strategy.VerifiedOnly- 如果核查失败或称为不可核查的函数,则放弃例外.Strategy.VerifyIfPossible- 仅验证可核查的 rpc 方法,如果该方法不能核查,则使用倒接手或 rpc 方法,但如果核查失败,则使用例外.Strategy.WarningWithFallback- 总是使用默认提供者或 rpcs 来获取响应,并在可能时同时对响应进行核查。 如果核查失败,警告汉德勒被叫来(这仍可能是一个例外)。 如果失败, 使用 rpc 提供者的响应 .
new Colibri({ proofStrategy: Strategy.VerifyIfPossible }) -
warningHandler- 一种功能,在使用警告策略和出现核查错误时使用。 如果不设定, 默认将仅使用控制台. warn 来记录错误 .new Colibri({ warningHandler: (req, error) => console.warn(`Verification Error: ${error}`) }) -
fallback_provider- EIP 1193 供货商作为所有无法核查的请求的倒置,如 eth send Transaction。 也用于在verifyTransactions已启用.new Colibri({ fallback_provider: window.ethereum }) -
verifyTransactions- 如果真实, 所有 eth send Transaction 的电话在广播前都会被验证, 以防止交易操纵攻击 。 要求数fallback_provider准备就绪。 (默认:虚假)new Colibri({ fallback_provider: window.ethereum, verifyTransactions: true })
大楼
要从源头构建 Javascript 绑定, 您需要 安装了标记 编辑 EMSDK 环境变量指向它的安装目录.
Colibri JS-Binding已经用4.0.3版本进行了测试。 使用最新版本或其他版本可能导致出人意料的问题。 例如版本4.0.7不起作用. 安装时一定要选择正确的版本 !
建议的方法:使用 CMake 预设
该项目包括: CMakePresets.json 用于更容易配置的文件.
- 设置环境变量 : 确保
EMSDK环境变量指向您的 Emscripten SDK 目录.export EMSDK=/path/to/your/emsdk - 使用预设配置 : 使用
wasm预设.- 在VS代码/ursor中: 选择
[wasm]通过状态栏或命令调色板配置预设( r)CMake: Select Configure Preset) (中文(简体) ). - 在命令行上 :
# Configure (from the project root) cmake --preset wasm -S . # The binary directory (e.g., build/wasm) is defined in the preset
- 在VS代码/ursor中: 选择
- 构建 :
- 在VS代码/ursor中: 使用构建按钮或命令调色板(
CMake: Build) (中文(简体) ). 确保[wasm]选择了构建预设. - 在命令行上 :
# Build (using the build directory from the preset) cmake --build build/wasm -j
- 在VS代码/ursor中: 使用构建按钮或命令调色板(
此预设自动设置 -DWASM=true, (中文(简体) ), -DCURL=false,并基于您的 EMSDK 变量。 您可以在 CMakeUserPresets.json 如果您需要不同的 CMake 旗帜( 例如 ), -DETH_ACCOUNT=1) (中文(简体) ).
替代方法:手册 emcmake
如果你不愿使用预设,或者你的环境不能很好地支持它们:
- 设置环境变量 : 保证
EMSDK设置和标记环境是活动的(例如通过source ./emsdk_env.sh) (中文(简体) ). - 配置和构建 :
替换git clone https://github.com/corpus-core/colibri-stateless.git && cd colibri-stateless mkdir build/wasm-manual && cd build/wasm-manual # Use a dedicated build dir # Ensure EMSDK is set correctly before running emcmake emcmake cmake -DWASM=true -DCURL=false <other_flags> ../.. make -j<other_flags>带有任何额外的 CMake 选项( 如-DETH_ACCOUNT=1) (中文(简体) ).
在成功构建(使用两种方法)后,JS/WASM模块将被纳入配置的构建目录 emscripten 子文件夹(例如, build/wasm/emscripten) (中文(简体) ).
调试wasM
在追踪作为WASM运行的C核心中的bug时,有两种方法取决于您需要的详细程度.
浏览器中的源级 C 调试( 建议)
这个 wasm-debug CMake 预设将生成一个装满的 WASM 构建 妇女权利司 调试信息 。 与Chrome扩展合并 C/C++ 开发工具支助(DWARF),这允许在 C 源文件中设置断点,检查变量和结构,并在 Chrome DevTools 中直接通过 C 代码.
-
安装 Chrome 扩展 C/C++ 开发工具支助(DWARF)。 。 。 .
-
使用调试预设构建 :
cmake --preset wasm-debug cmake --build build/wasm-debug -
服务项目根( 这样可以访问构建输出和源文件) :
python3 -m http.server 8080 -
在 Chrome 中打开调试测试带 :
http://localhost:8080/bindings/emscripten/test/debug.html -
打开 DevTools( F12), 到 来源 选项卡。 在WASM模块加载后,您的 C 源文件出现在文件树上. 设置断点, 选择一个测试框, 然后单击 Run .
说明: DWARF扩展只在浏览器标签上工作,不在Node.js检查会话. 对于C级调试,总是使用浏览器方法.
调试构建使用 -O1 改为 -O0 以保持加密操作(BLS, SHA256)的合理速度,同时保存大多数调试信息。 如果需要以性能为代价的全可变能见度,则更改 -O1 改为 -O0 内 bindings/emscripten/CMakeLists.txt。 。 。 .
节点.js 测试调试(JS级)
调试 JavaScript / TypeScript 层, 或在堆栈痕迹中看到 C 函数名, 而无需完整源头映射 :
cd bindings/emscripten
node --inspect-brk --test test/rpc.test.mjs
然后打开 chrome://inspect 在Chrome中,并点击"inspect"在Node.js目标上. 您可以在 JS/ TS 文件设置断点, 在调用堆栈中查看可读 C 函数名( 通过 --profiling-funcs),但C源脚步在此模式中不可用.
还有VS代码/光标发射配置 "WASM节点测试(检查)" 自动启动调试器.
概念
Colibri背后的理念是创建一个超光度客户端——或更确切的验证器——可以用于网站,移动应用程序,尤其是嵌入式系统. 验证器是您应用程序或后端中用于创建给定数据有效证明的库. 验证器是客户端(或嵌入式系统)上用来验证该证明的库.
核查者是无国籍的:它只需要目前的同步委员会(它每~27h旋转一次),而这个委员会可以被缓存,按要求取出,或者用证据交付. 使用它,核查者可以验证任何其签名与同步委员会已核实的公钥相匹配的证明——允许在不处理每个块头的情况下对任何设备进行独立核查(如经典光客户端所做的那样).
许可证
麻省理工学院——见主要 仓库 详细情况.