Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

はじめに

最終更新: 2026-08-10

このドキュメントは、STARK Ballot Simulator の公開向けガイドです。 STARK Ballot Simulator は投票の完全性を段階的に検証する教育・ポートフォリオ向けの PoC であり、実運用の選挙基盤ではありません。

目的

  • システムの全体像を短時間で把握できるようにする
  • 暗号プロトコルと検証パイプラインの設計根拠を説明する
  • 検証手順を再現できる情報を提供する

公開状態

本書は、ライブデモと公開用ソース snapshot の読者に向けたドキュメントです。 公開 repository snapshot は hwatanabe-jp/stark-ballot-simulator-public で確認できます。

再現手順は、対象リリースの bundle.zip と対応する公開 repository snapshot を照合して実行してください。 必要な材料と bundle.zip 単体では揃わない証拠は 第三者検証ガイド にまとめています。

公開仕様は、runtime、検証、artifact の 3 つの境界を説明します。 これらは利用者、監査者、実装追跡者が確認できる範囲です。 内部の作業記録や運用証跡は本書の範囲外であり、完了状態として主張しません。

想定読者

  • 暗号検証や監査、本アプリケーションの設計に関心のある技術者

本書の用語表記

本書では、語彙の揺れを避けるために次の表記へ統一します。 詳細な定義は 用語集 を参照してください。

  • 日本語に統一する語：コミットメント（文脈に応じて「投票コミットメント」「入力コミットメント」を区別）、包含証明、整合性証明、投票レシート、掲示板、ジャーナル
  • 英語のまま使う語：STARK、zkVM、Image ID、RFC 6962、capability、bundle.zip、fail-closed、finalization（集計確定）
  • 識別子は原文のまま：ファイル名、API フィールド、契約名（journal.json、verificationStatus など）はコードフォントの英語表記を保ちます。
  • コンポーネント名：概念としては「検証サービス」、バイナリ名・パスとしては verifier-service を使います。
  • 役割名とリソース名：概念・役割としては「プローバー」「検証 worker」、リソース・コンポーネント固有名（prover semaphore、proof-dispatcher、verification-worker など）は原文の英語表記を保ちます。

バンドル関連は、次の 3 語を使い分けます。

指すもの表記
配布されるファイル本体bundle.zip
配布対象としての論理名配布対象アーカイブ
非公開アーティファクトを含む上位概念証明バンドル

verification.json は protected report artifact であり、public bundle.zip のメンバーではありません。 階層関係は バンドル構造 と 公開境界 を参照してください。

本書の読み方

標準ルート

  1. まず 全体像 でシステムの概要を掴む
  2. 利用フロー で Home から Verify までの画面と API の流れを確認する
  3. 暗号プロトコル でコミットメントや Merkle ツリーなどの基盤を理解する
  4. zkVM 設計 でゲストプログラムと証明生成の仕組みを学ぶ
  5. 検証パイプライン で 4 段階検証モデルの全体と公開境界を把握する
  6. 改ざんシナリオ で教育的シミュレーションの動作を確認する
  7. 品質保証と形式手法 でテスト、PBT、Lean による品質境界を確認する
  8. AWS アーキテクチャ で runtime の責務分担を理解する
  9. API リファレンス でエンドポイント仕様を参照する
  10. 実際に検証する場合は 第三者検証ガイド で bundle.zip を使ったローカル検証手順を実行する

PoC として受け入れている制約は 全体像、 設計背景の一次資料は 参考文献 から参照してください。

読者別ルート

いずれも標準ルートの 1〜2（全体像、利用フロー）を読み終えていることを前提に、そこから先の重点だけを示します。

監査者向け

bundle.zip を検証ページから取得し、独立にローカル監査したい読者向けです。

  1. 検証パイプライン で /verify の最終判定ロジックを理解する
  2. 公開境界 で public bundle.zip と protected report artifact（verification.json）の境界を確認する
  3. チェック一覧 で各チェック ID と判定条件を確認する
  4. 第三者検証ガイド で bundle.zip のローカル監査手順を実行する

用語集 を手元に置き、テストと形式化が守る境界は 品質保証と形式手法 で補足してください。 飛ばしてよい: 暗号プロトコル の数式詳細、AWS アーキテクチャ のインフラ詳細

実装者向け

クライアント、サーバー、zkVM のいずれかの実装を変更または追従したい読者向けです。

  1. 暗号プロトコル でコミットメント、Merkle、入力コミットメントの正準形を把握する
  2. zkVM 設計 でゲストとホストの責務分担と Image ID 管理を理解する
  3. 検証パイプライン でチェック評価、ゲーティング、公開境界を把握する
  4. API リファレンス でエンドポイント仕様と session-scoped 認可を確認する

テストのレイヤー分担は 品質保証と形式手法 を参照してください。 飛ばしてよい: 第三者検証ガイド（実装変更後の動作確認には 改ざんシナリオ を使う方が早い）

運用者向け

AWS インフラ、非同期プローバー、デプロイを担当する読者向けです。

  1. AWS runtime 境界 で frontend、API、DynamoDB、async prover、artifact delivery の責務分担を把握する
  2. AWS アーキテクチャ で runtime 構成、環境分離、Terraform-managed infrastructure の連携点を把握する
  3. 非同期プローバー で SQS、Step Functions、ECS の責務を理解する
  4. 可観測性設計 で構造化ログ、検出、相関、通知境界を確認する
  5. イメージ署名 と Image ID で署名検証と Image ID 解決の連動を確認する
  6. 公開境界 と バンドル構造 で artifact の公開 / 保護境界を把握する

観測対象となるエンドポイントの契約は API リファレンス を参照してください。 飛ばしてよい: 暗号プロトコル の数式、改ざんシナリオ の教育的デモ詳細