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

エンドポイント一覧

この文書は、公開ドキュメントとして扱う API を対象に、現行実装のレスポンス形状・要件を記載します。

対象外（内部向け）

以下は内部運用/デバッグ用途のため、この文書の詳細対象外です。

  • GET /api/debug/enable
  • POST /api/finalize/callback

公開対象 API 一覧

メソッドパス主用途X-Session-ID
POST/api/sessionセッション作成不要
POST/api/vote投票送信必須
GET/api/progressボット投票進捗必須
POST/api/finalize集計/証明生成必須
POST/api/finalize/cancel非同期集計キャンセル必須
GET/api/sessions/:sessionId/status非同期集計ステータス不要
GET/api/verify検証ペイロード取得必須
POST/api/verification/runSTARK 検証実行必須
GET/api/verification/bundles/:sessionId/:executionIdバンドル ZIP 取得不要
GET/api/verification/bundles/:sessionId/:executionId/report検証レポート取得不要
GET/api/bulletin掲示板一覧必須
GET/api/bulletin/:voteId投票エントリ + 証明必須
GET/api/bulletin/:voteId/proof最小包含証明必須
GET/api/bulletin/consistency-proof整合性証明必須
GET/api/botdata/:idボット投票データ必須
GET/api/bitmap-proofビットマップ証明材料実装依存
GET/api/sthSTH スナップショット必須
GET/api/zkvm-input-hashzkVM 入力コミットメント不要

共通の実装上の注意

  • POST /api/vote と POST /api/finalize は Turnstile 検証を実行します。
  • POST /api/verification/run は Turnstile なしで、/api/finalize と同じ zkVM レート制限を使用します。
  • エラー形式はエンドポイントにより異なります（標準化 payload と独自 payload が混在）。

基本フロー API

POST /api/session

新規セッションを作成します。

レスポンス（200）:

  • data.sessionId
  • data.electionId
  • data.electionConfigHash
  • data.logId

備考:

  • このハンドラでは X-Session-ID は不要です。

POST /api/vote

ユーザー投票を保存し、ボット投票を非同期開始します。

要件:

  • ヘッダー: X-Session-ID 必須
  • ボディ: commitment, vote, rand（turnstileToken は開発設定により省略可）
  • Turnstile 検証あり
  • 投票用レート制限あり

レスポンス（200）:

  • data.voteId
  • data.commitment
  • data.bulletinIndex
  • data.bulletinRootAtCast
  • data.timestamp

主なエラー:

  • SESSION_ID_REQUIRED (400)
  • SESSION_NOT_FOUND (404)
  • CAPTCHA_FAILED (403)
  • GLOBAL_LIMIT_EXCEEDED (503)
  • ALREADY_VOTED (400)
  • SESSION_FINALIZED (400)
  • INVALID_VOTE_CHOICE (400)
  • INVALID_COMMITMENT (400)
  • DUPLICATE_VOTE (409)

GET /api/progress

投票進捗を取得します。

要件:

  • ヘッダー: X-Session-ID 必須

レスポンス（200）:

  • data.count
  • data.total
  • data.completed
  • data.userVoted
  • data.finalized

主なエラー:

  • SESSION_ID_REQUIRED (400)
  • SESSION_NOT_FOUND (404)

POST /api/finalize

集計と証明生成を開始します。同期/非同期の 2 形態があります。

要件:

  • ヘッダー: X-Session-ID 必須
  • ボディ: scenarioId（S0-S5）, turnstileToken（環境により必須）
  • Turnstile 検証あり
  • zkVM レート制限あり

レスポンス（200, 同期）:

  • data.sessionId
  • data.tally
  • data.bulletinRoot
  • data.verifiedTally
  • data.voteReceipt
  • data.receipt（同期成功レスポンスで返却）
  • data.receiptPublication（保存時）
  • data.imageId
  • data.userVote
  • data.missingIndices
  • data.invalidIndices
  • data.countedIndices
  • data.totalExpected
  • data.treeSize
  • data.sthDigest
  • data.includedBitmapRoot
  • data.inputCommitment
  • data.verificationStatus
  • data.verificationBundleUrl / data.verificationReportUrl / data.verificationReport（条件付き）
  • data.verificationExecutionId（条件付き）
  • data.s3BundleUrl / data.s3BundleKey / data.s3UploadedAt / data.s3BundleExpiresAt（条件付き）
  • data.tamperSummary（条件付き）

レスポンス（202, 非同期）:

  • executionId
  • statusUrl
  • state
  • queue（null の場合あり）

主なエラー:

  • SESSION_ID_REQUIRED (400)
  • SESSION_NOT_FOUND (404)
  • CAPTCHA_FAILED (403)
  • INVALID_REQUEST (400)
  • VERIFICATION_FAILED (400, CT proof unavailable)
  • USER_NOT_VOTED (400)
  • VOTING_NOT_COMPLETE (400)
  • SESSION_ALREADY_FINALIZED (400)
  • ZKVM_RATE_LIMIT_EXCEEDED (429)
  • GLOBAL_LIMIT_EXCEEDED (503)
  • Invalid ImageID (400, 独自形式 { error: "Invalid ImageID", details: { expected, actual } })

POST /api/finalize/cancel

進行中の非同期集計をキャンセルします。

要件:

  • FINALIZE_ASYNC_MODE=true のときのみ有効
  • ヘッダー: X-Session-ID（x-session-id も受理）
  • ボディ: executionId 必須、reason 任意

レスポンス（200）:

  • state

主なエラー（このエンドポイントは独自形式）:

  • 404: Async finalization disabled / Session not found
  • 400: ヘッダー欠落、JSON 不正、payload 不正
  • 409: 現在状態ではキャンセル不可
  • 500: Session store unavailable
  • 501: ストアが cancellation 非対応

GET /api/sessions/:sessionId/status

非同期集計の状態を返します。

要件:

  • パスパラメータ sessionId 必須

レスポンス（200）:

  • sessionId
  • finalizationState（null の場合あり）
  • queue（null の場合あり）
  • progress（条件付き）
  • finalizationResult（null の場合あり）
  • stepFunctions（条件付き）
  • asyncFinalizationMode（enabled / disabled）

主なエラー（独自形式）:

  • 400: Session ID is required
  • 404: Session not found

検証 API

GET /api/verify

検証画面向けの統合ペイロードを返します。

要件:

  • ヘッダー: X-Session-ID 必須
  • クエリ: refreshS3=1, includeJournal=1（任意）

レスポンス（200）:

  • data.electionId
  • data.electionConfigHash
  • data.logId
  • data.tally
  • data.bulletinRoot
  • data.scenarioId
  • data.verificationStatus
  • data.verificationBundleUrl / data.verificationReportUrl / data.verificationReport（条件付き）
  • data.verificationSteps / data.verificationChecks
  • data.s3BundleUrl / data.s3BundleKey / data.s3UploadedAt / data.s3BundleExpiresAt（条件付き）
  • data.imageId
  • data.tamperDetected
  • data.verifiedTally
  • data.missingIndices
  • data.invalidIndices
  • data.countedIndices
  • data.totalExpected
  • data.treeSize
  • data.excludedCount
  • data.sthDigest
  • data.includedBitmapRoot
  • data.inputCommitment
  • data.seenIndicesCount（条件付き）
  • data.journalStatus
  • data.journal（includeJournal=1 のとき）
  • data.voteReceipt（条件付き）
  • data.userVote（条件付き）
  • data.botVotesSummary（条件付き）
  • data.verificationExecutionId（条件付き）
  • data.tamperSummary（条件付き）

特殊レスポンス:

  • verificationStatus が許容セット外の場合、400 VERIFICATION_FAILED を返しつつ、data.verificationSteps / data.verificationChecks を返します。

主なエラー:

  • SESSION_ID_REQUIRED (400)
  • SESSION_NOT_FOUND (404)
  • SESSION_NOT_FINALIZED (400)
  • USER_NOT_VOTED (400)

POST /api/verification/run

サーバー側で STARK レシート検証を実行します。

要件:

  • ヘッダー: X-Session-ID 必須
  • ボディ: JSON オブジェクト（通常は空オブジェクト {}）
  • zkVM レート制限あり

レスポンス（200）:

  • data.verificationStatus（success / failed / dev_mode / not_run / running）
  • data.verificationExecutionId
  • data.estimatedDurationMs
  • data.idempotent

挙動:

  • 既存結果がある場合や実行中の場合は、再実行せず idempotent: true を返します。

バンドル取得 API

GET /api/verification/bundles/:sessionId/:executionId

証明バンドル bundle.zip を返します。

レスポンス:

  • 200: ZIP バイナリ
  • 302: S3 presigned URL へリダイレクト
  • 400: パラメータ不正
  • 404: バンドル未検出
  • 500: ダウンロード URL 生成失敗 / 読み込み失敗

GET /api/verification/bundles/:sessionId/:executionId/report

検証レポート verification.json を返します。

レスポンス:

  • 200: JSON
  • 302: S3 presigned URL へリダイレクト
  • 400: パラメータ不正
  • 404: レポート未検出
  • 500: ダウンロード URL 生成失敗 / 読み込み失敗

掲示板 API

GET /api/bulletin

掲示板一覧を返します。

要件:

  • ヘッダー: X-Session-ID 必須
  • クエリ: offset, limit（任意）

レスポンス（200）:

  • commitments
  • bulletinRoot
  • treeSize
  • timestamp
  • rootHistory（条件付き）
  • nextOffset / hasMore（ページング時）

主なエラー:

  • SESSION_ID_REQUIRED (400)
  • SESSION_NOT_FOUND (404)
  • INVALID_OFFSET (400)
  • INVALID_LIMIT (400)

GET /api/bulletin/:voteId

投票単位の包含証明を返します。

要件:

  • ヘッダー: X-Session-ID 必須
  • パス: voteId（UUID v4 形式）

レスポンス（200）:

  • voteId
  • commitment
  • bulletinIndex
  • merklePath
  • bulletinRootAtCast
  • treeSize
  • proofMode（rfc6962）

主なエラー:

  • INVALID_VOTE_ID (400)
  • VOTE_NOT_FOUND (404)
  • VERIFICATION_FAILED (400, CT proof unavailable)

GET /api/bulletin/:voteId/proof

最小形式の包含証明を返します。

要件:

  • ヘッダー: X-Session-ID 必須
  • セッションは finalized 必須
  • パス: voteId

アクセス制御:

  • 原則は「そのセッションのユーザー投票」のみ
  • 例外としてシナリオ S3/S4 では対象ボット票を許可

レスポンス（200）:

  • voteId
  • proof.leafIndex
  • proof.merklePath
  • proof.treeSize
  • proof.bulletinRootAtCast
  • proof.proofMode

キャッシュ:

  • ETag 対応
  • If-None-Match 一致時は 304

GET /api/bulletin/consistency-proof

RFC6962 整合性証明を返します。

要件:

  • ヘッダー: X-Session-ID 必須
  • クエリ: oldSize, newSize 必須

レスポンス（200）:

  • oldSize
  • newSize
  • rootAtOldSize
  • rootAtNewSize
  • proofNodes
  • oldSubtreeHashes / appendSubtreeHashes（条件付き）
  • timestamp

備考:

  • このエンドポイントは独自のエラー JSON を返します。

GET /api/botdata/:id

ボット投票（1..63）のデータと証明を返します。

要件:

  • ヘッダー: X-Session-ID 必須
  • セッション finalized 必須

レスポンス（200）:

  • data.id
  • data.vote
  • data.random
  • data.commitment
  • data.voteId
  • data.timestamp
  • data.proof（leafIndex, merklePath, treeSize, bulletinRootAtCast, proofMode）

主なエラー:

  • INVALID_BOT_ID (400)
  • SESSION_NOT_FINALIZED (400)
  • BOT_DATA_NOT_FOUND (404)

補助 API

GET /api/bitmap-proof

ビットマップ包含証明の材料を返します。

要件:

  • クエリ: i（0 以上整数）必須
  • X-Session-ID はストア実装依存（Mock/File は省略可、Amplify は実質必須）
  • 互換性のため X-Session-ID の指定を推奨

レスポンス（200）:

  • leafChunk
  • auditPath

キャッシュ:

  • ETag 対応
  • If-None-Match 一致時 304
  • Cache-Control: private ... immutable

エラー（独自コード）:

  • INVALID_INDEX (400)
  • BITMAP_NOT_FOUND (404)
  • INTERNAL_ERROR (500)

GET /api/sth

STH スナップショットを返します。

要件:

  • ヘッダー: X-Session-ID 必須
  • finalized セッションのみ

レスポンス（200）:

  • sth.sthDigest
  • sth.bulletinRoot
  • sth.treeSize
  • sth.timestamp
  • sth.logId

備考:

  • 現行実装の sth.timestamp はジャーナル内時刻ではなく、session.lastActivity を返します。

主なエラー:

  • SESSION_ID_REQUIRED (400)
  • SESSION_NOT_FOUND (404)
  • SESSION_NOT_FINALIZED (404, このエンドポイント固有の扱い)

GET /api/zkvm-input-hash

セッション由来の zkVM 入力コミットメントを返します。

要件:

  • クエリ: sessionId 必須
  • クエリ: includeData 任意（true / 1 / yes で有効）

レスポンス（200）:

  • inputCommitment
  • data（includeData 有効時のみ）

主なエラー（独自形式）:

  • INVALID_REQUEST (400)
  • SESSION_NOT_FOUND (404)
  • SESSION_NOT_FINALIZED (400)
  • CT_PROOF_UNAVAILABLE (400)
  • INTERNAL_ERROR (500)