如何为你的代码验证比特币时间戳证明
一份你自己无法核验的时间戳证明,不过是包装得更漂亮的供应商承诺。迟早会有人——专利纠纷中的律师、尽职调查中的审计员,或是怀疑你的"独立实现"并不独立的 CTO——要求你出示某个提交哈希在某个日期确实存在。那一刻就是验证环节,而它恰恰是大多数团队从未演练过的一步。
好消息是:借助 Timestamp GIT,验证并不是什么研究课题。GitHub App 每晚为你的提交哈希做锚定,检查一份证明只需一次点击、一个 URL 或一条 curl 命令。本文逐一讲解具体的验证路径、结果的含义,以及边界情况藏在何处。
为什么验证很重要:从信任到证明
主张与证据之间有着本质区别:
- 主张是"我们在三月写了这个"。它存在于你控制的数据库中,可以被编辑。
- 证据是"这个特定的提交哈希被包含在一棵 Merkle 树中,而该树的根被嵌入在比特币区块 N 中"。任何人都可以重新计算它。
对于合规、审计和诉讼而言,证据还有一个额外要求:它必须可重复,且独立于供应商。如果你的证明只有在某家公司的服务器在线时才能验证,那它就不是真正的证明——而是一份订阅服务。
Timestamp GIT 的设计考虑到了这一点。.ots 收据加上公开的比特币区块数据就是完整的证明。验证路径中没有任何专有组件,也无需在你的开发者机器上安装任何东西。本文专注于验证环节;如果你还在决定是否要做时间戳,战略层面的论证见我们的创始人现有技术指南。
比特币时间戳证明究竟包含什么
单日的证明由两件产物组成,存放在专用的 timestamps 分支或影子仓库中,以便与你的代码一同进行版本管理:
- 清单文件(
.txt),列出该仓库当天收集到的提交哈希。 .ots收据文件,包含将你的哈希链接到比特币中所锚定 Merkle 根的 Merkle 路径。
链条如下所示:
commit hash ─┐
commit hash ─┼─ Merkle tree ─ Merkle root ─ Bitcoin transaction ─ block
commit hash ─┘ │
.ots receipt (Merkle path from your hash to the root)
验证时有两个特性至关重要:
- 清单证明哪些哈希被包含在内。
.ots收据证明 Merkle 根何时进入链中。
由于锚定仅使用 OpenTimestamps 协议、不含任何专有内容,这份证明在我们消失后依然有效:它就是 SHA-256 加上比特币区块数据,可离线验证,永久有效。
分步操作:使用 Timestamp GIT 验证时间戳证明
1. 从 README 中的徽章开始
每个受监控的仓库都可以显示一个 Shields.io 验证徽章。它是一个实时指针,而非静态图片:它链接到该仓库的公开状态页。你可以在仓库连接页面(https://timestampgit.dev/connected/{user}/{repo})生成嵌入代码片段,粘贴前会显示实时预览。
<!-- Paste the snippet generated at /connected/{user}/{repo} -->
[](https://timestampgit.dev/status/OWNER/REPO)
当审查者点击徽章时,他们会直接落到证据上——而不是营销页面。
2. 阅读仓库状态页
打开:
https://timestampgit.dev/status/{user}/{repo}
这个公开仪表盘提供便于审计的摘要:
- 证明可追溯时长——你的锚定历史可以回溯多久。
- 最早锚定日期——你的哈希首次进入比特币的那一天。
- 每日规律性——证明夜间任务确实日复一日地运行。
- 锚定的比特币区块和交易数据。
- 日历热力图,让缺口一目了然。
- 下载:审计 CSV 和 PDF 证书。
对审计员来说,热力图加上 CSV 通常足以完成第一轮检查。缺失的方格才是需要调查的地方。
3. 在本地验证特定日期
如需日期级别的证明,打开:
https://timestampgit.dev/verification/{user}/{repo}/{date}
此页面逐步展示 Merkle 链,并在你的浏览器中本地执行计算。你所验证的内容不会被传输——零知识特性同样适用于验证,而不仅仅是数据摄取。
这一点比听起来更重要。合规审查者可以检查涉及敏感内部仓库的证明,而无需向供应商提供任何额外信息。
4. 通过 API 拉取 Merkle 链
如果你更愿意以编程方式验证(或将证据存入自己的合规系统),API 会返回特定日期的完整 Merkle 链数据:
curl -s "https://timestampgit.dev/api/verify/OWNER/REPO/2026-11-18" | jq
你还可以获取最近锚定的区块和当前提交计数:
curl -s "https://timestampgit.dev/api/statusLast/OWNER/REPO" | jq
curl -s "https://timestampgit.dev/api/statusCount/OWNER/REPO" | jq
无需 CLI 工具、无需协议命令、无需钱包软件。繁重的工作——通过 GitHub App webhook 检测提交、批处理、构建 Merkle 树以及比特币锚定——已经在夜间完成。
解读结果——以及边界情况
一份有效的证明意味着一个狭窄而强有力的结论:该提交哈希在此比特币区块的时间戳之时或之前已经存在。 它并不告诉你代码质量如何、每一行是否由你编写,或由谁输入。哈希之外的作品归属是另一个问题——我们对Git 提交时间戳能否作为证据的分析涵盖了这一区别。
其他需要记住的事项:
- 区块时间戳偏差。 比特币区块时间戳可能与实际时间略有偏差。无论如何,证明在密码学上依然强健,因为区块本身不可篡改——没有人能重新挖矿历史来移动你的锚点。
- 某日期缺少证明。 证明在午夜后几小时才会写入:cron 工作进程批处理哈希、构建 Merkle 树、提交到公共 OTS 日历,然后等待比特币确认——通常约三小时。某天的证明可能尚未写入。如果已超过这个时间,请检查该仓库在那段时间是否确实受到监控。
- 私有仓库。 私有仓库的状态 URL 带有加密的 HMAC,只有持有该 URL 的人才能查看状态。验证本身仍在浏览器中本地进行。
- 自托管实例。 每个实例生成自己的 HMAC。如果你将徽章从 SaaS 实例迁移到自己的 Docker 部署,请重新生成徽章链接——来自一个实例的 HMAC 无法在另一个实例上通过验证。
不依赖 SaaS 的验证:Docker 自托管与离线检查
对于气隙隔离或高度偏执的环境,Timestamp GIT 以 Docker 镜像形式提供。一个快速上手的 Docker Compose 配置如下:
services:
timestampgit:
image: rue1401/timestampgit:prod
ports:
- "8080:8080"
volumes:
- ./data:/app/data
restart: unless-stopped
valkey:
image: valkey/valkey:8
restart: unless-stopped
然后:
docker compose pull
docker compose up -d
docker compose logs -f timestampgit
应用可在 http://localhost:8080 访问,首次启动时的设置向导会引导你连接 GitHub App 并配置实例。如果你想在正式采用前进行评估,可从 Docker License 页面获取限时演示许可证。
自托管不会改变验证的数学原理。.ots 文件和比特币区块数据是相同的产物,且可离线验证。你可以完全手动操作,将 .ots 文件交给标准 OpenTimestamps 验证工具,对照本地比特币节点进行验证——这是硬核做法,而它之所以可行,正是因为证明独立于供应商。产品的查看器和 API 只是让它变成一键操作,而非一个周末项目。
为合规自动化验证
如果验证是季度审查中的一个勾选项,那就把它自动化:
- 导出账本。
GET /api/audit/{user}/{repo}以 CSV 返回完整审计账本——这正是审计员真正想要归档的产物。 - 生成每日证书。
GET /api/report/{user}/{repo}/{date}为特定日期生成 PDF 证书,适用于需要将单份证明附在合同或争议文件中的场景。 - 轮询新鲜度。 你这边的一个简短 cron 任务可以捕获真正重要的故障模式:锚定悄然停止。
#!/usr/bin/env bash
set -euo pipefail
REPOS=("acme/api" "acme/web" "acme/infra")
for repo in "${REPOS[@]}"; do
printf '%-14s ' "$repo"
curl -s "https://timestampgit.dev/api/statusLast/${repo}" | jq -c '.'
done
每天运行它;如果最近锚定的区块不再推进,你就能在审计员之前发现问题。
- 公开显示状态。 嵌入 Shields.io 徽章,让下游用户和客户无需向你询问即可看到验证状态。
对于希望最大程度隔离的团队,Enterprise ZK 方案提供一个简短的 GitHub Action,在你自己的 CI 中运行,仅传输提交哈希——锚定和验证模型保持不变,验证仍在本地进行。
常见问题
验证证明需要运行任何 OpenTimestamps 命令吗?
不需要。Timestamp GIT 提供基于 Web 的验证页面和 REST API,可处理整个检查过程。如果你愿意,也可以下载 .ots 文件并使用标准验证工具,但这并非必需。
证明需要多长时间才能变得可验证?
证明每晚锚定,并在几小时后于比特币区块链中确认——通常约三小时。今天做出的提交,到明天就会有可验证的证明。
我可以验证私有仓库的证明吗?
可以,但私有仓库状态页需要在 URL 后附加加密的 HMAC。授权用户可以访问,验证本身仍在你的浏览器中本地进行。
如果 Timestamp GIT 消失了怎么办?我还能验证吗?
可以。证明独立于供应商:它仅依赖 SHA-256 和比特币区块数据。即使我们的服务不复存在,你也可以使用标准 OpenTimestamps 工具离线验证 .ots 文件。
结论
验证是时间戳从"好主意"变成可辩护证据的地方。工作流程很短:点击徽章、阅读状态页、打开日级验证视图,或访问 /api/verify/{user}/{repo}/{date} 自行检查 Merkle 链。每条路径都通向同一个终点——一个在特定比特币区块之前就已存在的提交哈希,可永久证明,无需信任任何人的数据库。
如果你还没开始,设置是最枯燥的部分:在仓库上安装 GitHub App,让夜间任务运行起来。到明天你就会拥有第一份可验证的证明。前往 timestampgit.dev 连接你的第一个仓库。