在 Cardano 上发布你的第一份存在性证明

最简单的 Label 309 证明，就是一个锚定在 Cardano 上的哈希。

你拿一个文件，计算它的加密哈希，把这个哈希写进一条 Label 309 记录、放在 Cardano 元数据 label 309 下发布，然后保存好生成的交易哈希。日后，任何人只要持有原始文件，就能重新计算哈希，确认匹配的哈希承诺已上链，且时间不晚于该交易的区块时间。要验证这一点，他们不需要你的服务器、你的域名，也不需要你的身份——只需要交易引用和一个公开的 Cardano 浏览器。

这就是存在性证明的第一层，其余的一切都建立在它之上。本指南将带你完整发布一份证明，主要使用 cardanowall 命令行工具，并在最后讲清楚如何确认它确实成功了。

你实际发布的到底是什么？

当你创建一份基础证明时，你并不是在发布文件本身。

你发布的是对文件的一个承诺：它的摘要。摘要是一段固定长度的加密指纹。文件只要变动一个字节，摘要就会彻底改变。正是这一特性，使哈希成为那一串确切字节的可靠替身。

仅含哈希的证明很适合用在这些场景：

合同与发票
发布产物与构建清单
AI 输出与数据集快照
政策文件与证据材料包
另一套系统已经生成好的校验和

证明不会暴露文件内容，它只会暴露哈希、你选用的哈希算法，以及你决定写进记录的任何可选元数据。关于哪些字段会上链，详见哪些内容会写上区块链。

发布之前你需要准备什么？

发布需要一个网关，验证则不需要。

验证完全依靠公开的链上数据运行。发布则不同：必须有人来构建并提交 Cardano 交易、支付网络手续费、处理确认，并且——如果你把文件存到链下——支付存储费用。Label 309 网关就是负责完成这一切的服务。开源网关及其周边工具都是网关无关的，所以你可以把工具指向任何一个你持有密钥的网关。

发布你的第一份证明，你需要：

一个文件，或一份预先算好的摘要
一个 Label 309 网关的基础 URL
该网关的一个 API 密钥，或短期有效的账户令牌
网关账户上有足够的余额
可选的身份种子，前提是你想给记录签名

如果你使用托管的 CardanoWall 网关，CardanoWall 会替你打理网关账户和预付余额。如果你自建网关，则由你自己为它的 Cardano 钱包和存储钱包充值。无论哪种方式，发布都要花钱，因为系统会代你支付真实的费用——这正是为什么发布需要付费要讨论的话题。

为什么流程是先报价、后发布？

网关绝不应该悄无声息地发布，然后用一张账单让你措手不及。所以每一次发布都遵循同样的两步走结构：先锁定价格，再提交。

构建或估算记录。
向网关请求报价。
收到一个报价 id 和一份费用明细（网络手续费、存储、服务利润）。
携带该报价提交最终的记录。
立刻收到一个网关记录 id，此时交易其实还在提交过程中。
持续跟踪状态，直到交易在链上得到确认。
独立地验证结果。

报价会在一个有限的时间窗内锁定价格——目前是 15 分钟。如果在你发布之前报价过期了，就重新请求一个；价格可能因为汇率变动而变化，但其他一切都不会变。

正是这种两步走的模式，让自动化变得安全。你的脚本可以记录报价、执行自己的支出策略，然后才发布——这样无论是价格突然飙升，还是手滑误触的批量任务，都绝不会把你的余额花得失控。

用 CLI 发布一个文件

对于本地文件，命令行流程刻意保持简短：

cardanowall submit \
  --file ./contract.pdf \
  --base-url https://your-gateway.example \
  --api-key "$CARDANOWALL_API_KEY"

CLI 会对文件计算哈希、构建 Label 309 记录、请求网关报价并发布，然后打印结果。--base-url 和 --api-key 也可以从 CARDANOWALL_BASE_URL 和 CARDANOWALL_API_KEY 这两个环境变量读取，因此在 CI 里可以从命令中省去它们。

如果要反复使用，与其每次都传入端点地址，不如把网关保存为一个命名配置：

cardanowall gateway add prod --base-url https://your-gateway.example
cardanowall gateway use prod
cardanowall submit --file ./contract.pdf

cardanowall 这个二进制文件是一个单一、自包含的原生工具，无需安装任何运行时。你可以从 crates.io 用 cargo install cardanowall-cli 安装它（crate 名为 cardanowall-cli，安装后的命令是 cardanowall），也可以从 github.com/cardanowall 的开源仓库自行构建。

如果哈希已经有了，要怎么发布？

有时候摘要本来就已经存在——来自构建流水线、容器镜像仓库、发布流程，或者某个数据归档。这种情况下，直接发布摘要即可，完全不涉及文件：

cardanowall submit --hash <64-hex-digest>

默认的哈希模式是 sha2-256。当你需要换用 BLAKE2b-256 算法时，加上 --alg blake2b-256。记录会标明你用了哪种算法，这样验证方日后才知道该怎么重新计算摘要。

当源文件太大、太敏感，或受到太严格的管控、不便经由一个通用工具流转时，发布预先算好的哈希也是正确的做法。唯一要紧的，是确切的字节和确切的哈希计算过程必须保持可复现——否则没人能重新算出一个匹配的摘要。

你该不该给记录签名？

当你想证明某个特定的 Label 309 身份为这条记录背书时，就给它签名。

一份仅含哈希的证明说的是：这些字节在此时间前已经存在。 一份已签名的证明则补充道：而且这个签名密钥为这条确切的记录背书。 这条额外的主张，对于公司发布记录、官方归档、CI/CD 流水线、法律证据流程、AI 来源溯源日志，以及任何长期存在的公开发布者身份，都很重要。

签名始终是可选的。一份未签名的证明，仍然是一份完整、可被完全验证的存在性证明——Label 309 在设计上就是发布者无关的，验证方从来不必信任发布者。签名只是回答了另一个不同的问题：是谁为记录背书，而不是字节是否存在过。

身份种子绝不能发送给网关。CLI 和 SDK 的构建方式确保签名在本地完成，只有最终签好的签名会向外传输。请通过 --seed-stdin 或 --seed-file 提供种子，而不要用裸的 --seed 参数，因为命令行参数会经由 shell 历史记录、进程列表和 CI 日志泄露出去：

cardanowall submit --file ./release-manifest.json --seed-stdin

是该把文件一并附上，还是只放哈希？

你有三个选择，按上链所承诺的内容由少到多排列。

仅含哈希。 体积最小、隐私性最强的证明。当你已经确定文件会被保存在某个你能掌控的地方时，它就足够了。这条记录只携带摘要，不含任何检索信息。

哈希加上一个内容寻址链接。 附上一个 ar://（Arweave）或 ipfs://（IPFS）的 URI，让验证方日后能取回字节。最终仍然由哈希来判定取回的字节是否匹配——内容寻址的 URI 把字节绑定到链接本身，因此验证方无需信任网关、DNS 或 TLS，就能确认自己取回的是正确的文件。

封存。 加密文件，把密文存到链下，再把封存信封放进记录。当你需要保存机密记录、向某个指定接收方投递，或在本地副本丢失后还能取回内容时，这就是要走的路径。

发布第一份证明时，先从仅含哈希开始。等真正有用例需要时，再加上签名、链下存储、Merkle 批处理或封存投递。

你怎么知道它真的成功了？

不要停在「网关已经接受了它」这一步。只有当交易上链并通过验证，证明才算完整。

发布时，网关会立刻交还一个记录 id，而交易哈希会在交易构建并提交完成后异步补上。所以发布之后，请保存好：

Cardano 交易哈希
网关记录 id，如果你用了网关
原始文件或摘要
签名密钥的公开身份，如果你签了名
任何 Merkle 叶子列表或包含证明，如果你做了批处理
任何恢复材料，如果证明是封存的

然后，像任何第三方那样去验证这笔交易——从公开的链上数据出发，全程不涉及网关：

cardanowall verify <tx-hash> --json

得到 valid 这个结论，就到了终点。其他几种结论则告诉你下一步该做什么：

pending——交易还没有沉淀到足够的深度。等待更多确认后重试。
unverifiable——记录本身没有问题，但有一项必需的检查无法运行。检查你的数据源、链下存储的可用性以及网络策略。
failed——一个真实的、可归因于记录的问题。请深入排查记录本身。

failed 与 unverifiable 的区分是刻意为之的：failed 表示记录是错的，而 unverifiable 表示验证方没能完成某项检查。完整的验证流程，详见验证一条 Label 309 记录。

发布之后界面上该展示些什么？

一个好的界面，展示的内容应当不止「已发布」这一个词。对于第一份证明，请呈现出来：

简短的交易哈希，配一个复制按钮
详情视图里的完整交易哈希
哈希算法和摘要
发布状态
确认之后的区块时间
验证结论
记录是否经过签名
是否附带了文件或做了封存
是否有任何检查被跳过

这样一来，无须任何人去读标准文档，证明本身就能被看懂。

发布时可能出哪些岔子？

大多数发布失败都是运营层面的问题，并不神秘。账户可能余额不足。报价可能已经过期。记录可能对一笔 Cardano 交易而言太大。上传的文件可能存储失败。Cardano 交易可能永久性失败——这种情况下，一个构建良好的网关会自行冲销这笔费用，因此你只会为真正上链的部分付费。又或者，网关那个已充值的钱包只是单纯需要关照一下。

一套严肃的发布工作流，会以幂等的方式处理重试。网关会按记录的确切字节对发布重试做去重——重新提交完全相同的记录，会返回已有的结果，而不是花两次钱——并且在上传批次上接受一个幂等键，使得重复投递的上传能安全重放。在面向用户的产品里，请在你的第一个真实客户撞上网络超时之前，就把重试路径设计好，而不是事后才补。

如果你要把这套流程接进流水线，在自动化中使用 CLI 会更深入地讲解 JSON 输出、退出码以及密钥的安全处理。

你的第一份证明不能证明什么？

存在性证明对自己主张的内容很精确，这也意味着它对自己不主张的内容同样精确。

它不能证明所有权。
它不能证明作者身份——除非你给它签了名，并且能把签名密钥与所声称的身份关联起来。
它不能证明文件是真实、合法或原创的。
它不会保存文件，除非你把它存到某个持久之处。

它能证明的，则既精确又持久：与所承诺哈希相匹配的那一串确切字节，不晚于该交易的区块时间已经存在；并且任何可选的签名、存储检查或封存内容检查，都按验证方的策略通过了验证。

这已经足以带来真正的用处，也精确到足以被信任。关于一个时间戳能确立与不能确立的边界，更全面的论述参见一份证明不能证明什么。