TgWitness / ドキュメント

テスト済みの内容 →

参考文献 / 証拠

Telegram · 独立した証人

独自の鍵とボットを使用してWitnessを実行し、署名済みのチェックポイントをチャンネルに公開し、エクスポートしたデータと照合してください。

TgWitness / ドキュメント · 証拠と検証

証拠と検証

エクスポートと検証 · 高信頼性 · パネルガイド

ウィットネスは、コレクターとは別に署名付きチェックポイントを保持します。ウィットネスは、 コレクターの署名とジャーナルの連続性を検証し、その結果を自身の鍵で署名して、 Telegramチャンネルに公開します。コレクターのウィットネスエンドポイントへの読み取り専用アクセス権を持つ 別のサーバー上で実行してください。

技術的な結果には、保持されたジャーナルのプレフィックス、チャレンジ応答、署名チェック、Merkleの包含/整合性チェック、署名付きの連続性の結果が含まれます。別の保管者が運用するWitnessについては、保管者の情報と鍵管理記録を、そのフィンガープリントとともに保持してください。鍵の分離と保管の分離は、構成の別々の部分を表します。検証ツールは、2つ目の鍵がジャーナルのヘッドをどの記録まで保持したかを報告し、保管者の鍵管理記録がその鍵を誰が保持しているかを示します。Witnessジャーナルは補助的なチェックであり、証拠としての最低要件は第三者による時刻です。チャンネル投稿は外部時刻を加えます。Telegramが各公開投稿に日付を付け、検証ツールがその日付を自ら読み取ります。

フローチャートコレクター → ウィットネス (署名付きチェックポイント:記録数 + 先頭ハッシュ); ウィットネス → Witnessジャーナル、独自の鍵; ウィットネス → Telegramチャンネル (独自のボットを介して署名付きで投稿されました); 証拠 ZIP → verify.py; Witnessジャーナル、独自の鍵 → verify.py; Telegramチャンネル → verify.py (t.me/s ページをリアルタイムで閲覧、またはデスクトップへエクスポート)コレクターウィットネスWitnessジャーナル、独自の鍵Telegramチャンネル証拠 ZIPverify.py署名付きチェックポイント:記録数 + 先頭ハッシュ独自のボットを介して署名付きで投稿されましたt.me/sページをリアルタイムで閲覧、またはデスクトップへエクスポート
図表をテキストで記述
  1. コレクター → ウィットネス (署名付きチェックポイント:記録数 + 先頭ハッシュ)
  2. ウィットネス → Witnessジャーナル、独自の鍵
  3. ウィットネス → Telegramチャンネル (独自のボットを介して署名付きで投稿されました)
  4. 証拠 ZIP → verify.py
  5. Witnessジャーナル、独自の鍵 → verify.py
  6. Telegramチャンネル → verify.py (t.me/s ページをリアルタイムで閲覧、またはデスクトップへエクスポート)
このページでは

Witnessが保持するもの#

Witnessには このツールには決して
1つのワークスペース用の読み取り専用ウィットネストークン コレクターのTelegramセッションまたはAPI認証情報
独自のEd25519鍵とジャーナル コレクターの保管庫、署名鍵、またはパネルトークン
独自のTelegramボットトークン メッセージの内容:ヘッダーには記録件数とハッシュ値が含まれます

トークンは「その他のツール」→「エクストラ」→「独立したウィットネス」で作成され、一度だけ表示され、 SHA-256としてのみ保存されます。これはGET /api/witness/headというエンドポイントを正確に1つだけ開き、このエンドポイントは新たに 署名されたチェックポイントに加え、署名済みのコンテンツを含まない収集カウンターおよび運用状態を返します。 このトークンでは、パネルを開いたり、メッセージの内容を読み取ったり、設定を変更したりすることはできず、 パネル用トークンもここでは受け入れられません。トークンの無効化は同じページで行います。コレクターは、 新しいウィットネスキーがチェックを開始した時刻(witness.seen)を記録し、トークンごとの最後のチェック日時を表示します。 2.5のインターバル以内にチェックが行われていないウィットネスは、期限切れとしてマークされます。

新しいウィットネスは、 各ポーリングごとにランダムなチャレンジを送信します。キャプチャステートメントは、コレクターの署名の下でそれを反映します。カウンターは 正確なチェックポイントに紐付けられており、署名付きウィットネス投稿に含まれます。レガシーヘッドは スタンドアロンのウィットネスによって引き続き受け入れられます。ジャーナルの増分のみは、決して新しいメッセージとしてカウントされることはありません。

チェックおよび記録の対象#

一定の間隔(デフォルトでは10分ごと)ごとに、witnessは以下の処理を行います:

  1. ヘッド自体を取得します(コレクターはこれをプッシュしたりスキップしたりすることはできません);
  2. コレクターの署名、固定されたコレクターキー(--collector-fingerprint、 または最初に検出されたキー)、非減少するカウント、および変更されていないカウントにおける変更されていないヘッドを検証します。 マークル包含証明および整合性証明は、増加するジャーナルが 保持されているチェックポイントを拡張していることを検証します。連続性証明が一度使用されると、その削除は拒否されます。
  3. 自身のジャーナルに署名付きレコードを追加します:witness.anchor(ステータス:ok、 key_changed、rollback(以前よりレコード数が少ない)、fork(長さは同じですが、 ヘッダーが異なる)、またはinvalid(検証に失敗した)、あるいはwitness.no_response( コレクターが応答しなかった場合));
  4. TgWitnessが 稼働中でBot APIにアクセス可能な間は、「no answer」を含め、署名付きの結果をチャンネルに投稿します。投稿ID(witness.posted)が記録され、 投稿に失敗した場合も同様に記録されます(witness.post_failed)。

投稿は次のような形式になります。最後の行には署名付きの記述が含まれています:

TgWitness witness #42 · journal head
Collector 3fa9c2d1e0b4a7f6: 18234 records
Head 9b1f…c07e
2026-10-28T19:40:00.123+00:00
TGW1.eyJhdCI6…<statement>.<signature>

witnessを実行する#

Telegramボット(@BotFatherで作成してください)、そのボットが 管理者となっているチャンネル、および証人からアクセス可能なコレクターのアドレス(プライベートネットワーク外で HTTPS経由)が必要となります(導入手順の「HTTPSプロファイル」を参照してください)。

開く [その他のツール] → [エクストラ] → [独立したウィットネス] → [設定] パネル内。3つのステップで、 読み取り専用アクセス、チャネルと間隔の設定、そしてウィットネスの起動が行われます。公開 ポリシー、オプションのHTTP/SOCKS5プロキシ、およびカスタムBot APIアドレスは 詳細設定。このフォームは ダウンロードします witness.json このワークスペースのコレクターキーが固定された状態で。新しく 作成された読み取り専用トークンを アクセスファイルを保存 as witness-token.txt; それを、および bot-token.txt witnessホスト上で作成されたbot-token.txtを、そのJSONファイルの隣に配置してください。コレクターはボットトークンを受け取ることはありません。 ダウンロードによってサービスが起動されたり、メッセージが公開されたりすることはありません。ホストされたプロジェクトのウィットネスは 暗黙的に登録されません。

python -m tgwitness.witness run --config witness.json --check-config
python -m tgwitness.witness run --config witness.json
python -m tgwitness.witness fingerprint --config witness.json

最初のコマンドは、ネットワークリクエストや鍵の 生成を行わずに、設定ファイルと秘密ファイルを確認します。JSON内のパスはそのファイルを基準とした相対パスであり、CLI/環境のパスは 作業ディレクトリを基準とした相対パスです。 ウィットネスのフィンガープリントは、ホストの外に保持してください。コレクターの 「last-poll」インジケーターはリクエストの確認のみを行います。公開については、Proof によって報告されるか、 ウィットネス・ジャーナルおよびチャンネルで確認してください。

パネルがSSHトンネルの背後に配置されている場合は、このCaddyの例に従い、 別のHTTPSホスト名上で、スコープが限定されたwitnessエンドポイントのみを公開してください。 その場合、デフォルトのワークスペースではhttps://witness.example.orgが使用され、その他のワークスペースでは https://witness.example.org/profiles/IDが使用されます。トークンは引き続き必要となります。パネルおよびその その他のAPIルートは、その仮想ホストによって転送されません。

定期的にチェックポイントが公開される設定には「all」をお選びください。5分間隔の場合、ワークスペース1つあたり1日約288件の 投稿となります。「changes」および「problems」では、一部のチェックポイントを意図的に非公開としています。 MTProxyは、コレクター側のTelegramクライアント用です。WitnessのHTTPポーリングおよびTelegramのHTTPS Bot APIは、それぞれ独自のダイレクト/HTTP/SOCKS5ルート(Bot API)を使用します。

コレクターの隣に、Docker を使用して(同じホスト上で — 独立したプロセスとキーですが、 オペレーターは同じです):.env に値を入力し、プロファイルを起動してください。

TGWITNESS_WITNESS_TOKEN=tgww_...
TGWITNESS_WITNESS_BOT_TOKEN=123456:ABC...
TGWITNESS_WITNESS_CHANNEL=@your_witness_channel
# another workspace: TGWITNESS_WITNESS_COLLECTOR=http://tgwitness:8787/profiles/<workspace ID>

docker compose --profile witness up -d
docker compose logs witness     # prints the witness key fingerprint

掲載されている画像を使用する場合は、docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d をご使用ください。

他者のサーバー上(分離管理)では:リポジトリをそこにコピーし、 TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org に加えて上記の3つの値を .envに設定してから、

docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d

または、Docker を使用しない場合:

python -m tgwitness.witness run --collector https://your-collector.example.org \
    --token-file witness-token.txt --bot-token-file bot-token.txt --channel @your_witness_channel

Discordに公開する#

ウィットネスは、Telegramの代わりにDiscordチャンネルに投稿することもできます。Discordで、 「チャンネルの編集」→「統合」→「Webhook」を開き、Webhookを作成してそのURLをコピーします。 パネル内のステップ2で、「Discord Webhook・あなたのチャンネル」を選択します。ウィットネスホスト上で、 そのURLを discord-webhook.txt の横に witness.jsonの横に保存してください。このURLは コレクターには決して送信されません。

python -m tgwitness.witness run --collector https://your-collector.example.org \
    --token-file witness-token.txt --discord-webhook-file discord-webhook.txt

ウィットネスには1つのパブリッシャー(TelegramチャンネルまたはDiscordウェブフックのいずれか一方)があり、両方を兼ねることはできません。投稿 には同じ署名付きステートメントが含まれ、誰に対してもpingを送信することはできません。Discordの 2,000 文字を超える投稿は、短い行に置き換えられ、完全なチェックが witness-check.txt として添付されます。各投稿IDはwitness.posted として記録されます。verify.py --channel はTelegramチャンネルのみを読み取るため、Discordの場合はウィットネスのジャーナルを保持してください。そこにはすべての チェックが記録されています。Discordの投稿からは、検証者に外部時刻は提供されません。

オプション#

オプション 環境 デフォルト 意味
--interval TGWITNESS_WITNESS_INTERVAL 10 チェック間隔(分):1~1440
--timeout _TIMEOUT 30 コレクターおよびBot APIの応答待ち時間は数秒、5~600
--post _POST all all:すべてのチェック;changes:新たな課題または問題;problems:問題と未回答のみ
--title _TITLE TgWitness witness 各チャンネルの投稿の冒頭部分
--collector-fingerprint _COLLECTOR_FINGERPRINT – 最初の回答を鵜呑みにするのではなく、コレクターキーを固定してください
--proxy _PROXY 直接 socks5://host:port または http://host:port
--bot-api _BOT_API https://api.telegram.org Bot APIのアドレス(例:ローカルのBot APIサーバー)
--data-dir _DATA witness-data Witnessキーとジャーナル
--config _CONFIG – 上記のいずれかのオプションを含むJSONファイル

コレクターアドレス、トークン、チャンネルは以下から取得されます --collector, --token または --token-file, --bot-token または --bot-token-file, --discord-webhook-file および --channel、 または _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE, _DISCORD_WEBHOOK_FILE および _CHANNEL、これにより、プロセス一覧から秘密情報が除外されます。

設定ファイルでは、アンダースコア付きのオプション名に加え、texts を使用します。これは、 チャンネルの投稿文を置き換えるものです:

{"collector": "https://your-collector.example.org", "token_file": "witness-token.txt",
 "bot_token_file": "bot-token.txt", "channel": "@your_witness_channel",
 "interval": 5, "timeout": 30, "post": "changes", "title": "Partner witness",
 "texts": {"ok": "journal head", "no_response": "no answer from the collector", "records": "records"}}

textsキー:ok、key_changed、rollback、fork、invalid、no_response、collector、 records、head。コマンドラインの設定が環境変数より優先され、環境変数がファイルの設定より優先されます。 未知のオプションやテキストキーは、無視されるのではなく、メッセージを表示してウィットネスを停止させます。 記述内容は検証には一切影響しません。verify.py は、すべての 投稿の最後に署名付きトークンをチェックします。--post changesやproblemsを使用した場合でも、投稿されなかったチェックは依然として ウィットネス・ジャーナルに残っており、verify.pyはそれらを「未投稿」として一覧表示します。開始レコードには ポリシー名が記載されます。すべてのチェックは依然としてジャーナルに表示されるため、投稿数が少ないということは、Telegramによる日付の付与回数が 少なくなるだけであり、チェックの数が減るわけではありません。

チャンネルがなくても、Witnessは引き続きジャーナルを保持します。Witnessのキーフィンガープリント (python -m tgwitness.witness fingerprint)は別の場所に保管してください。

複数のワークスペースの公開証明ページ#

python -m tgwitness.proof witnessesは一度に最大32のワークスペースを管理し、各ワークスペースの最新の署名済みチェック結果を 読み取り専用ページとして提供します。各ワークスペースには、dataフォルダ内に独自のwitnessキーと ジャーナル、および固定されたコレクターキーが割り当てられます。Telegramチャンネルへの投稿は、 ワークスペースごとに任意です。まずは proof.config.exampleから始めてください:

分野 意味
title ページタイトル(1~100文字)
data_dir ファイルに関連付けられたWitnessの鍵とジャーナル。デフォルト proof-data
interval, timeout チェック間隔(分単位:1~1440、デフォルトは5);待機時間(秒単位:5~600、デフォルトは20)
workspaces[].id, label 短い小文字のエイリアスと表示名
workspaces[].collector コレクターのアドレス。その他のワークスペースは「」で終わります。 /profiles/<workspace ID>
workspaces[].collector_fingerprint 必須。ワークスペースごとに異なります。
workspaces[].token_file そのワークスペースの読み取り専用ウィットネストークンを含むファイル
workspaces[].channel, bot_token_file オプション:各チェック結果をチャンネルに投稿する
workspaces[].proxy, bot_api オプションのルートおよびBot APIアドレス
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790

最初のコマンドは、接続を開くことなくファイルとトークンファイルの有効性を検証します。 このページは GET および HEAD メソッドのみに応答します:

  • / すべてのワークスペースが表示されます。2.5 インターバルの間、チェックが入っていないワークスペースは「stale(古くなった)」とマークされます。
  • /api/proof JSONと同じ内容を返します。
  • /api/proof/<id> 最新の署名付きステートメントをダウンロードします(tgwitness-public-proof-v1): ウィットネス記録番号とハッシュ、ステータス、固定されたコレクターキー、チェックポイント、収集 カウンター、およびチャンネルへの投稿が成功したかどうか。これらは、そのワークスペースのウィットネスキーによって署名されています。
  • /healthz ワークスペースのモニターが停止すると、503エラーが返されます。

Caddyfile.proof.example のように、ページに独自のホスト名を割り当ててください。検証のために、 ワークスペースのウィットネス・ジャーナルを python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip でエクスポートし、 以下に説明する通りに使用してください。

検証#

証人側では、そのジャーナルをエクスポートします:

python -m tgwitness.witness export --out witness.zip
# Docker (add -f deploy/compose/compose.witness.yaml on a witness server):
docker compose exec witness python -m tgwitness.witness export --out /witness/witness.zip
docker compose cp witness:/witness/witness.zip .

その後、どこからでも、コレクターの署名付きZIPファイルとパブリックチャンネルのアドレスを使用して:

python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
    --witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/your_witness_channel

--channelは、Telegram Desktopからのエクスポート(「チャット履歴をエクスポート」→「JSON」を選択すると result.jsonが生成されます)や、ページの保存コピーも受け付けます。これらは投稿内容を検証しますが、 外部時刻は提供しません。

verify.pyは、ウィットネスのジャーナル(チェーンと署名)を検証した後、ウィットネスが確認したすべてのヘッドが エクスポートされたジャーナルに含まれているかを確認します。つまり、そのカウント位置にあるレコードは、正確に そのハッシュ値を持たなければなりません。 一致しないヘッドは検証に失敗します — ジャーナルは、 ウィットネスがそれを確認した後に変更されたことになります。また、エクスポート後に確認されたヘッド、ウィットネスが 記録した異常、失敗した応答、この エクスポートに一致するチェックポイントが存在する期間(「XからYまでウィットネス済み」)、およびギャップも報告されます。それ以降のチェックポイントは、それらの期間を延長しません。 結果には、最後の一致したレコード番号と、一致するチェックポイントのない 後続のレコード数が含まれます。 エクスポート自身の鍵で署名された回答のみがカウントされます。ウィットネスが 一度も確認したことのない鍵で署名されたエクスポートは「未確認」として報告され、--fingerprintを指定しない限り、その 署名者は未固定のままとなります。--channelを指定した場合、署名されたすべての投稿はウィットネスのジャーナルと レコードごとに一致する必要があります。変更された投稿は検証に失敗し、欠落している投稿は一覧表示されます。トークンが 一致することでコンテンツの真正性が認証されますが、日付は署名されたトークンの範囲外となります。

有効なhttps://t.me/s/…またはhttps://telegram.me/s/…アドレスがあれば、検証者は 検証時にページから各投稿の日付を読み取ります。 Telegramがその日付を設定します。 編集された投稿の日付は使用されません。エクスポートヘッドにおける投稿の最も早い日付は、 証拠の最小条件を満たす最後のレコードの外部 時刻となります。提供されたresult.json、保存されたページ、または他のWeb アドレスなど、その他のソースからの日付は、独立した時刻ではなく、提供されたメタデータです。結果には、その投稿 日付の出典が明記されています(post_date_verification)。

証人付きエクスポートの境界が必要です#

立会人の立会いのもとで作成された最終記録を含める必要がある引き継ぎの際は、--require-witnessを追加してください:

python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
    --witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness

これには、独立して保持されたウィットネスのフィンガープリント、 コレクターキー以外のキー、およびこのエクスポートの正確な末尾に位置する一致するチェックポイントが必要です。より早いプレフィックスのみを カバーするチェックポイントでは不十分です。収集を一時停止し、ウィットネスに 最終状態を観察させ、ジャーナルへのさらなる書き込みが行われる前にエクスポートしてください。ジャーナルが変更された場合は、別のチェックポイントを保持し、 その状態をエクスポートしてください。後のチェックポイントだけでは、より短いエクスポートの最終ハッシュを検証することはできません。 --channelも指定されている場合、主張された投稿の欠落や空のマッチセットがあると、この 厳格なチェックに失敗します。このフラグがない場合でも、通常の整合性チェックでは、 アーカイブ自体が破損していなければ、証人による確認を受けていないレコードを報告するだけで、アーカイブそのものは拒否されません。

ウィットネス・ジャーナルとその固定キーは別々に保管してください。オンライン検証ではチェックポイント間の連続性が確認され、 オフライン検証では保持されているすべてのチェックポイントが エクスポートデータと比較されます。連続性の証明がないレガシー・ヘッドについては、オフライン比較の結果が保持され、 オンライン連続性検証なしにレポートされます。レポートには、ウィットネスのダウンタイムおよび 間隔ごとの公開失敗が一覧表示されます。

デイリーシールおよび利用不可のタイムスタンプカレンダー#

ウィットネスは、前日のUTC時点のジャーナルの境界を封印し、 その署名付き封印のハッシュをOpenTimestampsに送信します。カレンダーへの送信は未確定の証拠であり、 独立して検証されたビットコインのコミットメントのみが、検証者において確認されます。

すべてのカレンダーが失敗した場合、署名付きシールと失敗した試行は ジャーナルに残ります。1時間ごとのメンテナンスパスは、再起動後や日付変更後を含め、 その元のレコードを再試行します。最大32個のシールをスキャンし、最大 2件の未送信データを送信し、1パスあたりの再試行に最大60秒を費やします。 永続的なカーソルが古いシールを順番に処理します。保持された送信データは、 既存のプルーフアップグレードパスに従います。

再試行を行っても、シールが書き換えられることはなく、元の日付が変更されることも、 カレンダーがそれより早く受信したと主張されることもありません。後に行われたビットコインのコミットメントは、依然として後発の外部 確認として扱われます。欠落している証明はnoneのままとなり、保留中の証明は、 検証者が独自に確認を行うまでpendingのままとなります。