EIP-2696: JavaScript `request` 方法 RPC 传输

简述

当以太坊 Provider 和以太坊 Client 都能通过共享的 JavaScript 对象彼此连接时，用于它们之间远程过程调用的标准。

摘要

本标准提供了一种对象的描述，该对象提供给 JavaScript 应用程序，它们可以使用它与以太坊区块链进行通信。本标准仅描述传输机制，不指定有效负载，也不指定客户端或 Provider 如何发现或商定有效负载内容。

如何/在何处公开此以太坊对象留给未来的标准。

动机

在 JavaScript 运行时（例如 NodeJS、Electron、Browser 等）中工作时，运行时或运行时插件可能会将对象注入到运行时中。编写运行时或运行时插件的人可以选择将以太坊 Provider 公开给在该运行时中运行的任何 JavaScript 应用程序或脚本，以便提供对类以太坊区块链和潜在签名工具的间接访问。为了在 Provider 和客户端之间实现最大兼容性，有必要制定一个关于该对象形状的标准。

规范

RFC-2119

本文档中的关键词“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY”和“OPTIONAL”应按照 RFC-2119 中描述的进行解释。

接口

TypeScript 接口定义：

interface RequestArguments {
	readonly method: string;
	readonly params?: readonly unknown[] | object;
}

interface EthereumProvider {
	request(args: RequestArguments): Promise<unknown>
}

Provider MUST 在公开的 EthereumProvider 对象上实现 request 方法。request 方法 MUST 可以使用单个参数调用，该参数包含请求的参数，如上面的 TypeScript interface 中定义。

如果 Provider 支持在其他地方指定的 JSON-RPC (https://www.jsonrpc.org/specification) 请求，则它 MUST 接受对该 JSON-RPC 方法的 request 调用，其中 RequestArguments.method 参数与 RPC 调用的 JSON-RPC method 字符串匹配，并且 RequestArguments.params 与 RPC 调用的 params 对象匹配。RequestArguments.params 应该编码为与指定的 JSON-RPC 类型匹配的 JavaScript 对象，而不是像通常传输 JSON-RPC 时那样编码为 JSON 字符串。

示例

如果 JSON-RPC 请求包含如下有效负载：

'{ "jsonrpc": "2.0", "id": 1, "method": "do_work", "params": [ 5, "hello" ] }'

那么匹配的 EthereumProvider.request 调用将是：

declare const provider: EthereumProvider
provider.request({ method: 'method', params: [ 5, 'hello' ] })

结果

如果 Provider 在其他地方支持指定的 JSON-RPC 请求，则它 MUST 返回一个与关联的 JSON-RPC 请求的预期 result 定义匹配的对象。

示例

如果 JSON-RPC 响应包含如下有效负载：

'{ "jsonrpc": "2.0", "id": 1, "result": { "color": "red", "value": 5 } }'

那么匹配的 EthereumProvider.request 响应将是：

{ color: 'red', value: 5 }

错误

interface ProviderRpcError extends Error {
	message: string;
	code: number;
	data?: unknown;
}

如果 Provider 由于任何原因无法满足请求，则它 MUST 将 Promise 解析为一个错误。只要有可能，解析的错误 MUST 必须塑造为上面定义的 ProviderRpcError。虽然无法保证 JavaScript 应用程序永远不会抛出内存不足或堆栈溢出错误，但应注意确保 Promise 拒绝在可能的情况下符合上述形状。

如果提供了上面列表中、JSON-RPC 规范（https://www.jsonrpc.org/specification#error_object）中或正在遵循的关联 JSON-RPC 请求标准中列出的 code，则错误原因 MUST 必须与该代码的既定含义一致，并且 message MUST 必须与提供的 message 匹配。

data 字段 MAY 包含与错误相关的任何数据，或有助于用户理解或排除错误的数据。

理由

虽然此标准可能不是应用程序和区块链之间通信的最佳机制，但它与社区内已建立的实践紧密结合，因此从现有系统迁移到此标准应该相对容易。大多数通信当前通过 JSON-RPC 进行，因此希望与 JSON-RPC 标准保持一致，以便能够与现有系统快速集成。

安全注意事项

以太坊 Provider 和客户端之间的关系是可信赖的关系，假设用户隐式信任以太坊 Provider，这就是它设法注入到客户端中的方式，或者客户端明确地建立了与它的连接。

版权

版权和相关权利通过 CC0 放弃。

Citation

Please cite this document as:

Micah Zoltu (@MicahZoltu), Erik Marks (@rekmarks), "EIP-2696: JavaScript `request` 方法 RPC 传输," Ethereum Improvement Proposals, no. 2696, June 2020. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-2696.