OnFinality
新用户订阅 RPC,首月享 6.5 折优惠查看优惠
OnFinality Learn
集成与开发阅读约 8 分钟

区块链应用中的保密标志:含义、实现与验证

了解保密标志能做什么、不能做什么,掌握如何实现带有保密策略的元数据,并通过 RPC 端点验证实际行为。

TL;DR

保密标志通常是由应用定义的标记,用于通知软件将记录、请求或交易按敏感数据处理。设置标志本身不会自动加密数据,也不会带来链上隐私。公有区块链协议通常没有名为 `confidential` 的通用 JSON-RPC 字段,因此需要由应用、智能合约、钱包、索引器或支持隐私功能的协议定义该标志。本指南解释这一标志的工作原理,使用 `RPC_URL` 和 `PRIVATE_KEY` 等占位符说明实现方式,并给出可复现的验证流程。文中还介绍了标志的安全边界,以及在确实需要保密时应采取的控制措施。

保密标志的含义与适用范围

保密标志是一个布尔值或枚举值,用于改变软件处理数据的方式。例如,应用可以设置 confidential: true,让日志不输出敏感字段、限制 API 访问、选用加密后的载荷,或指示索引器不公开可选的元数据。具体行为取决于定义该字段的系统。

标志本身不是实现隐私保护的基础机制。如果明文值已经发布到交易输入、事件、calldata 字段、区块或公共数据库中,加上保密标记也不会隐藏该值。任何能访问这些公开数据的人仍然可以查看、复制和归档它。

对于常规区块链 RPC,除非网络的协议文档明确规定了密码学隐私机制,否则应将 confidential 视为应用元数据。区分这两者有助于避免一个常见的设计错误:以为标签可以改变数据发布后的可见性。

  • 标记:记录预期采用的处理策略。
  • 加密:转换数据,使未经授权的读取者无法理解其内容。
  • 访问控制:决定谁可以获取或解密数据。
  • 保密交易协议:改变交易内容或状态的披露方式。

协议边界与数据可见性

大多数标准区块链 JSON-RPC 方法定义的是通信与账本操作,例如获取区块、提交交易或读取合约状态。对于含有自定义应用字段的请求,服务提供商可能会转发请求、拒绝请求或忽略这些字段,具体取决于节点和中间件的实现。不要仅凭字段名称判断网络是否支持它。

使用标志前,先确认它定义在哪里:智能合约 ABI、钱包 SDK、API 模式、索引器、私有交易服务,还是某个网络特有的隐私功能。权威文档应说明允许的取值、默认行为、字段是否持久化,以及哪些参与方可以看到它。

在兼容 EVM 的公有网络上,合约可以将标志存入状态,或通过事件发出标志,但状态变更和事件通常都可被外部观察。私有 RPC 路由可以保护应用与服务提供商之间的数据传输,却不一定能让由此产生的区块链状态保持私密。

  • 集成前,记录字段由谁定义以及所用版本。
  • 区分传输保密性与账本保密性。
  • 检查日志、追踪记录、内存池数据和索引器数据库是否会暴露被标记的内容。
  • 如果隐私行为取决于特定链,请在支持的网络目录中查阅该网络的指南。

安全模型与威胁假设

在选择实现方式前,先明确哪些内容必须保密。威胁可能来自外部观察者、公共索引器、其他应用用户、泄露的 RPC 凭据,或有权访问日志的运营人员。单个布尔值无法应对所有这些威胁。

可以将数据流分为四个位置:客户端、RPC 传输链路、待处理交易或内存池,以及已最终确认的链上数据。TLS 可以保护与 HTTPS 端点之间的连接,但端点运营方仍可能处理请求。一旦明文数据进入公开交易或事件,事后加密或脱敏都无法恢复其保密性。

为每个字段制定明确的策略。例如,可以将公开标识符存储在链上,在客户端加密敏感值,发布承诺值或哈希以供日后验证,并通过经过身份验证的链下服务分发解密密钥。不要认为哈希天然具有保密性:如果输入的熵较低,就可以猜测输入并比对哈希。

  • 保密目标:哪些人不能看到这个值?
  • 保护期限:需要保护多久?
  • 完整性目标:读取者是否需要证明该值未被篡改?
  • 可用性目标:原客户端不可用时,谁能恢复该值?

应用层实现方式

对于常规应用,应在带版本的模式中定义标志,而不是在标准 RPC 参数旁添加一个未记录在文档中的属性。一条实用的记录可以包含公开记录标识符、策略版本、布尔值或模式、密文或承诺值,以及链下引用。应用随后在数据接收、存储、日志记录和检索各环节一致地执行该策略。

不要仅仅因为请求包含 confidential: true,就把敏感值发送给不可信的端点。如果不能让 RPC 运营方看到该值,请在构造请求前加密。不要将密钥纳入版本控制,也不要把密钥放入浏览器打包产物或交易 calldata。

以下示例将一份由应用定义的 JSON 文档发送到 API 路由。它不是标准的区块链 JSON-RPC 方法;请将 RPC_URL 替换为你自己的服务文档中指定的路由。此示例用来说明标志的含义,并不代表节点会执行相应策略。

  • 校验 schemaVersion,拒绝未知的策略模式。
  • 在应用日志中对载荷和凭据做脱敏处理。
  • 明确返回策略处理结果,例如 accepted、rejected 或 unsupported。
  • 分别测试启用和未启用保密标志的处理路径。
curl -X POST "$RPC_URL/v1/records" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  --data '{
    "schemaVersion": 1,
    "confidential": true,
    "payload": "CLIENT_SIDE_CIPHERTEXT",
    "commitment": "OPTIONAL_COMMITMENT"
  }'

链上表示与合约验证

如果合约需要记录某个工作流程遵循保密策略,只存储必要的公开元数据即可。Solidity 合约可以记录一个布尔值和一个承诺值,但该布尔值仍然公开,也不会隐藏承诺所对应的值。只有之后公开并核验原始值和 nonce,才能通过承诺值证明两者一致。

如果标志是交易的一部分,应验证合约的实际行为,而不是依赖钱包界面或 SDK 属性。确认 ABI 编码、发出的事件、交易回执状态以及最终写入的状态。如果合约忽略客户端附加的字段,交易仍可能成功,但预期的策略并没有被记录。

以下 JavaScript 示例通过 ethers 使用兼容 EVM 的 JSON-RPC 端点,在部署后读取合约的公开标志和承诺值。请用实际部署中的值替换占位符,不要在前端代码中放入私钥。

  • 读取状态前,确认合约地址和链 ID。
  • 将返回的标志与交易输入或部署配置比对。
  • 将返回的承诺值视为公开元数据,而不是秘密值本身。
  • 参考 RPC 端点文档,区分端点配置和合约行为。
import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
const contract = new ethers.Contract(
  process.env.CONTRACT_ADDRESS,
  [
    "function confidential() view returns (bool)",
    "function commitment() view returns (bytes32)"
  ],
  provider
);

const [confidential, commitment] = await Promise.all([
  contract.confidential(),
  contract.commitment()
]);

console.log(JSON.stringify({ confidential, commitment }, null, 2));

检查 RPC 请求与响应

如果标志由中间件或 API 网关实现,请先检查原始请求和响应,再排查链上问题。即使 HTTP 响应显示成功,应用层仍可能拒绝请求;而 JSON-RPC 错误也可能表示方法或参数不受支持。

先发送最简请求,再加上保密字段并比较响应。记录 HTTP 状态码、JSON-RPC 错误对象、请求标识符、返回的策略状态,以及响应中包含的交易哈希。切勿将 API 令牌、私钥、明文秘密值或已签名的原始交易粘贴到共享工单中。

以下 Python 示例比较两种在文档中有定义的应用层调用。它假定服务接受你自己的 API 约定中指定的方法,并不意味着所有区块链节点都实现了 setConfidentialFlag。

  • 关联重试请求与服务提供商的日志时,使用唯一的请求 ID。
  • 检查端点要求的是位置参数还是命名参数。
  • 比较响应结构,而不只是 HTTP 状态码。
  • 先用开发环境中的记录测试,再使用生产环境的标识符。
import os
import json
import requests

rpc_url = os.environ["RPC_URL"]
headers = {"Content-Type": "application/json"}

def call(params):
    body = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "setConfidentialFlag",
        "params": params
    }
    response = requests.post(rpc_url, headers=headers, json=body, timeout=20)
    response.raise_for_status()
    result = response.json()
    if "error" in result:
        raise RuntimeError(json.dumps(result["error"]))
    return result["result"]

print("without flag:", call({"recordId": os.environ["RECORD_ID"], "confidential": False}))
print("with flag:", call({"recordId": os.environ["RECORD_ID"], "confidential": True}))

验证结果与测量流程

可靠的测试既要验证标志是否按预期生效,也要检查数据是否暴露。创建两条除标志外条件相同的测试记录:一条禁用标志,另一条启用标志。使用非敏感载荷或本地生成的测试秘密值,然后检查客户端日志、网关日志、RPC 响应、交易回执、合约事件、公开区块浏览器或节点查询结果,以及下游索引器。

用表格记录结果,不要只看仪表盘上的标签。在自己的环境中完成测试前,将实测值留空。结果表可以包含以下列:测试项、预期行为、观察结果、证据和通过/失败。建议测试 API 是否接受请求、状态是否变更、事件是否可见、载荷是否暴露、重试行为,以及未经授权能否获取数据。

评估性能时,在相同的请求大小和并发量下重复每个用例。分别测量客户端感知延迟、错误率、确认延迟和载荷大小。不要根据一次未控制变量的测试来比较服务提供商或网络;应记录所用链、地区、软件版本、区块状态、并发量和时间戳。

  • API 接受情况:文档指定的路由接受该模式,或返回明确的“不支持”错误。
  • 持久化:确认后,预期的状态或元数据确实存在。
  • 暴露情况:在策略要求保护的所有位置均未发现敏感值。
  • 访问控制:未经授权的身份无法获取或解密该值。
  • 恢复:获授权的身份可以按文档规定的密钥处理流程恢复该值。

常见故障与排查方法

如果请求返回参数无效错误,先检查 API 或合约的模式。字段名为 confidential 并不意味着系统支持它。有些系统会拒绝未知字段,有些则会忽略它们。后者更危险,因为调用方可能误以为实际并未生效的保护已经启用。

如果应用响应中有标志,但链上状态中没有,请确认它是否仅为网关元数据。检查已签名的交易、交易回执、事件主题(topics)和合约存储。如果值出现在 calldata 或事件中,即使用户界面将它遮盖,也应将其视为公开数据。

如果保密措施偶尔失效,请检查重试流程、异步工作进程、队列载荷、追踪系统和死信存储。敏感数据常常从主数据库以外的环节泄露。请按照事件响应流程轮换已泄露的凭据或加密密钥;只改标志并不能补救。

如果不同端点的读取结果不一致,请对比链 ID、区块标签、已最终确认的状态以及服务提供商的响应。刚提交不久的交易不一定会同时出现在所有读取路径上。有关如何系统地排查端点差异,请参阅 RPC 可靠性与一致性指南。

  • 字段不受支持:移除该字段,或在文档指定的应用层实现它。
  • 字段被忽略:默认拒绝,要求服务器明确确认已处理该字段。
  • 明文已公开:将该值视为已泄露,并在可行时轮换或撤销。
  • 状态滞后:比较区块高度,并等待满足确认策略的要求。
  • 日志泄露:在数据源头做脱敏处理,并检查留存的遥测数据和备份。

设计取舍与运维限制

公开标记易于索引、审计和集成,但不提供保密性。客户端加密能更好地控制明文的暴露范围,却也带来了密钥管理、恢复、轮换和撤销的责任。承诺值可以保留可验证性,同时避免原始值被旁观者直接看到;但如果输入可预测,就可能被暴力猜出。

支持隐私功能的网络或保密执行环境可以降低公开可见性,但其保障取决于协议、受信任的组件、对验证者或运营方的假设,以及读取权限模型。应查阅网络的安全文档,而不是将服务提供商的端点当作保密性的证明。

在实际运维中,隐私控制可能增加延迟、载荷大小、故障恢复的复杂度和支持成本。应将保密范围限定在必要的最小范围内。适合公开的状态、时间戳和承诺值可以公开存储;如果不要求上链,则将敏感业务数据保存在专门设计的加密系统中。

选择基础设施时,应比较文档中列出的网络访问方式、身份验证、使用限制和可观测性,不要以为更换服务提供商就能改变协议的隐私特性。RPC 服务概览和 RPC 定价信息可帮助规划基础设施,但不能替代应用层加密或访问控制。

实施清单与后续步骤

先用直白的语言写明保密策略:保护什么、对谁保密、保护多久,以及哪些证据必须公开。然后梳理数据在客户端、RPC 请求、交易、日志、队列、数据库、索引器、备份和用户界面中的每一份副本。

接下来,定义带版本的模式,并在遇到不支持的模式时默认拒绝。如果 RPC 运营方不应看到敏感值,请在传输前加密;只发布验证所必需的承诺值或状态,并使用没有解密权限的身份测试未授权访问。

最后,在开发环境中按结果表所述流程运行测试,并保留复现所需的证据。若需进一步规划基础设施,可查阅多链 RPC 端点指南,了解专用节点选项。如果保密方案已经确定,只剩端点尚未选定,可使用 RPC Assistant 获取针对特定网络的简明端点建议。

  • 记录该标志属于应用元数据、合约状态还是协议功能。
  • 将秘密值和私钥保存在由运行环境管理的机密存储中。
  • 分别验证交易回执、事件、状态、日志以及索引器的数据暴露情况。
  • 先明确测试环境和验收标准,再开始测量。
  • 除非文档明确说明存在密码学隐私机制,否则只将保密标志视为策略信号。

永远不用担心基础设施

OnFinality 消除了 DevOps 的繁重工作,让您能够更聪明、更快地构建。

开始