TgWitness / Belgeler

Neler test edildi →

Referans / Kanıt

Telegram · Bağımsız tanık

Kendi anahtarı ve botu olan bir tanık çalıştırın, imzalı kontrol noktalarını bir kanala yayınlayın ve dışa aktarımları bu kontrol noktalarıyla karşılaştırarak doğrulayın.

TgWitness / Belgeler · Kanıt ve doğrulama

Kanıt ve doğrulama

Dışa aktarma ve doğrulama · Yüksek güvenilirlik · Panel kılavuzu

Bir tanık, imzalanmış kontrol noktalarını toplayıcıdan ayrı olarak saklar. Toplayıcının imzasını ve günlük sürekliliğini kontrol eder, sonucu kendi anahtarıyla imzalar ve bunu bir Telegram kanalında yayınlar. Toplayıcının tanık uç noktasına salt okunur erişimi olan ayrı bir sunucuda çalıştırın.

Teknik sonuç; saklanan günlük önekleri, sınama yanıtları, imza denetimleri, Merkle dahil etme/tutarlılık denetimleri ve imzalı süreklilik sonuçlarını içerir. Başka bir muhafız tarafından işletilen tanık için muhafızı ve anahtar kontrol kaydını parmak iziyle birlikte saklayın. Ayrı anahtarlar ve ayrı muhafaza, düzenin farklı bölümlerini tanımlar. Doğrulayıcı, ikinci bir anahtarın günlük başını hangi kayda kadar sakladığını bildirir; muhafızın anahtar kontrol kaydı bu anahtarın kimde olduğunu gösterir. Tanık günlüğü destekleyici bir denetimdir; kanıt için asgari koşul üçüncü taraf zamanıdır. Kanal gönderileri harici zaman ekler: Telegram her herkese açık gönderiyi tarihlendirir ve doğrulayıcı bu tarihleri kendisi okur.

Akış şemasıToplayıcı → Tanık (imzalı kontrol noktası: kayıt sayısı + başlık hash'i); Tanık → Witness günlüğü, özel anahtar; Tanık → Telegram kanalı (kendi botu aracılığıyla imzalanmış gönderi); Kanıt ZIP dosyası → verify.py; Witness günlüğü, özel anahtar → verify.py; Telegram kanalı → verify.py (t.me/s sayfası canlı olarak okunabilir veya masaüstü sürümüne aktarılabilir)ToplayıcıTanıkWitness günlüğü, özelanahtarTelegram kanalıKanıt ZIP dosyasıverify.pyimzalı kontrol noktası:kayıt sayısı + başlık hash'ikendi botu aracılığıylaimzalanmış gönderit.me/s sayfası canlı olarakokunabilir veya masaüstüsürümüne aktarılabilir
Diyagramın metin olarak gösterimi
  1. Toplayıcı → Tanık (imzalı kontrol noktası: kayıt sayısı + başlık hash'i)
  2. Tanık → Witness günlüğü, özel anahtar
  3. Tanık → Telegram kanalı (kendi botu aracılığıyla imzalanmış gönderi)
  4. Kanıt ZIP dosyası → verify.py
  5. Witness günlüğü, özel anahtar → verify.py
  6. Telegram kanalı → verify.py (t.me/s sayfası canlı olarak okunabilir veya masaüstü sürümüne aktarılabilir)
Bu sayfada

Tanığın sakladıkları#

Tanık şunlara sahiptir: Tanık hiçbir zaman
Bir çalışma alanı için salt okunur tanık jetonu Toplayıcının Telegram oturumu veya API kimlik bilgileri
Kendi Ed25519 anahtarı ve günlüğü Toplayıcının kasası, imzalama anahtarı veya panel jetonu
Kendi Telegram bot jetonu Mesaj içeriği: başlıkta kayıt sayısı ve bir hash yer alır

Jeton, Diğer araçlar → Ekstralar → Bağımsız tanık bölümünde oluşturulur, bir kez gösterilir ve yalnızca SHA-256 olarak saklanır. Tam olarak tek bir uç noktayı açar: GET /api/witness/head; bu uç nokta, yeni imzalanmış bir kontrol noktası ile imzalanmış, içerik içermeyen toplama sayaçları ve operasyonel durum bilgisini döndürür. Bu jetonla paneli açamaz, mesaj içeriğini okuyamaz veya ayarları değiştiremez; ayrıca panel jetonu burada kabul edilmez. Aynı sayfadan bir jetonu iptal edebilirsiniz. Toplayıcı, yeni bir tanık anahtarının ne zaman kontrol etmeye başladığını kaydeder (witness.seen) ve jeton başına son kontrolü gösterir; 2.5 aralık içinde kontrol yapmamış bir tanık, gecikmiş olarak işaretlenir.

Yeni tanıklar her oylamada rastgele bir doğrulama mesajı gönderir; yakalama ifadesi bunu toplayıcı imzası altında yineler. Sayaçlar tam kontrol noktasına bağlıdır ve imzalı tanık gönderilerine dahil edilir. Eski başlıklar bağımsız tanık tarafından kabul edilmeye devam eder. Günlüğün büyümesi tek başına asla yeni bir mesaj olarak sayılmaz.

Neleri kontrol eder ve kaydeder?#

Her aralıkta (varsayılan olarak 10 dakikada bir) TgWitness:

  1. başlığı kendisi alır (toplayıcı bunu zorlayamaz veya atlayamaz);
  2. toplayıcının imzasını, sabitlenmiş toplayıcı anahtarını (--collector-fingerprint, veya görülen ilk anahtar), azalmayan bir sayıyı ve değişmemiş bir sayıdaki değişmemiş başlığı doğrular. Merkle dahil etme ve tutarlılık kanıtları, büyüyen bir günlüğün saklanan kontrol noktasını genişlettiğini doğrular. Süreklilik kanıtları bir kez kullanıldıktan sonra, bunların kaldırılması reddedilir;
  3. kendi günlüğüne imzalı bir kayıt ekler: witness.anchor, durumu ok, key_changed, rollback (öncekinden daha az kayıt), fork (aynı uzunlukta, farklı başlık) veya invalid (yanıt doğrulamayı geçemedi) ya da witness.no_response (toplayıcı yanıt vermediğinde);
  4. Witness çalışırken ve Bot API'ye erişebiliyorken, sonucu "cevap yok" dahil olmak üzere imzalı olarak kanala gönderir. Gönderi kimliği kaydedilir (witness.posted), başarısız bir gönderi de kaydedilir (witness.post_failed).

Bir gönderi şu şekilde görünür; son satırda imzalı beyan yer alır:

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'ı çalıştırın#

Bir Telegram botuna (@BotFather ile oluşturabilirsiniz), bu botun yönetici olduğu bir kanala ve tanık tarafından erişilebilir bir toplayıcı adresine ihtiyacınız vardır — özel ağın dışında HTTPS üzerinden (kurulum bölümündeki HTTPS profiline bakın).

Aç Diğer araçlar → Ekstralar → Bağımsız tanık → Yapılandır panelde. Üç adımda salt okunur erişim, kanalınız ve aralık ayarları, ardından tanığın başlatılması ele alınır. Yayın politikası, isteğe bağlı HTTP/SOCKS5 proxy ve özel Bot API adresi Gelişmiş ayarlar. Form, indirme işlemini gerçekleştirir witness.json Bu çalışma alanının toplayıcı anahtarı sabitlenmiş olarak. Yeni oluşturulan salt okunur jetonu Erişim dosyasını kaydet gibi witness-token.txt; bunu ve bir bot-token.txt witness ana bilgisayarında oluşturulan bot-token.txt dosyasını bu JSON dosyasının yanına yerleştirin. Toplayıcı, bot jetonunu asla almaz. İndirme işlemi bir hizmeti başlatmaz veya mesaj yayınlamaz. Barındırılan proje tanığı örtük olarak kaydedilmez.

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

İlk komut, ağ isteği veya anahtar oluşturma gerektirmeden yapılandırma ve gizli dosyaları kontrol eder. JSON'daki yollar o dosyaya göredir; CLI/ortam yolları ise çalışma dizinine göredir. Tanık parmak izini barındırıcı dışındaki bir yerde saklayın. Toplayıcının son sorgulama göstergesi yalnızca bir isteği onaylar; yayınlama işlemi Proof tarafından bildirilir veya tanık günlüğü ve kanalında kontrol edilir.

Panel bir SSH tünelinin arkasında kalıyorsa, bu Caddy örneğini kullanarak yalnızca kapsam dahilindeki tanık uç noktasını ayrı bir HTTPS ana bilgisayar adında açığa çıkarın. Varsayılan çalışma alanı https://witness.example.org'yi kullanır, diğer çalışma alanları ise https://witness.example.org/profiles/ID'yi kullanır. Jetonlar hâlâ gereklidir; panel ve diğer API yolları bu sanal ana bilgisayar tarafından yönlendirilmez.

Düzenli olarak yayınlanan kontrol noktaları için all'yi seçin. Beş dakikalık aralık, her çalışma alanı başına günde yaklaşık 288 gönderi anlamına gelir. changes/problems, bazı kontrolleri kasıtlı olarak yayınlamaz. MTProxy, toplayıcının Telegram istemcisi içindir. Witness HTTP yoklaması ve Telegram’ın HTTPS Bot API’si kendi doğrudan/HTTP/SOCKS5 rotasını (Bot API) kullanır.

Toplayıcının yanında, Docker ile (aynı ana bilgisayar — bağımsız işlem ve anahtar, ancak aynı operatör): değerleri .env'ye girin ve profili başlatın.

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

Yayınlanan bir görsel kullanıldığında docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d kodunu kullanın.

Başka birinin sunucusunda (ayrı saklama): depoyu oraya kopyalayın, TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org ayarını ve yukarıdaki üç değeri .env dosyasına ekleyin, ardından

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

veya Docker olmadan:

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'da yayınla#

Bir tanık, Telegram yerine bir Discord kanalına gönderi paylaşabilir. Discord’da Kanal Düzenle → Entegrasyonlar → Webhook’lar’ı açın, bir webhook oluşturun ve URL’sini kopyalayın. Panelde, 2. adımda Discord webhook · kanalınız’ı seçin. Tanık sunucusunda, URL’yi discord-webhook.txt yanına witness.json; bu URL asla toplayıcıya ulaşmaz.

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

Bir tanığın tek bir yayıncısı vardır: bir Telegram kanalı veya bir Discord webhook’u; ikisi birden olamaz. Gönderiler aynı imzalı beyanı taşır ve kimseye ping atamaz. Discord’un 2,000 karakter sınırını aşan bir gönderi, tam kontrolün witness-check.txt olarak eklendiği kısa bir satırla değiştirilir. Her gönderi kimliği witness.posted olarak kaydedilir. verify.py --channel yalnızca Telegram kanallarını okur; bu nedenle Discord için tanık günlüğünü saklayın: bu günlük her kontrolü içerir. Discord gönderileri, doğrulayıcıya harici zaman bilgisi vermez.

Seçenekler#

Seçenek Ortam Varsayılan Anlam
--interval TGWITNESS_WITNESS_INTERVAL 10 Kontroller arasındaki süre, 1–1440
--timeout _TIMEOUT 30 Toplayıcı ve Bot API'sinin yanıt vermesi için bekleme süresi: 5–600 saniye
--post _POST all all: her kontrol; changes: yeni bir başlık veya bir sorun; problems: sadece sorunlar ve eksik cevaplar
--title _TITLE TgWitness witness Her kanal gönderisinin ilk kelimeleri
--collector-fingerprint _COLLECTOR_FINGERPRINT – İlk cevaba güvenmek yerine toplayıcı anahtarını sabitleyin
--proxy _PROXY doğrudan socks5://host:port veya http://host:port
--bot-api _BOT_API https://api.telegram.org Bot API adresi, örneğin yerel bir Bot API sunucusu
--data-dir _DATA witness-data Tanık anahtarı ve günlüğü
--config _CONFIG – Yukarıdaki seçeneklerden herhangi birini içeren JSON dosyası

Toplayıcı adresi, jetonlar ve kanal --collector, --token veya --token-file, --bot-token veya --bot-token-file, --discord-webhook-file ve --channel, veya _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE, _DISCORD_WEBHOOK_FILE ve _CHANNEL, bu da gizli öğeleri işlem listesinden uzak tutar.

Bir yapılandırma dosyası, alt çizgi içeren seçenek adlarının yanı sıra, kanal gönderilerindeki kelimelerin yerine geçen texts'yi kullanır:

{"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 anahtarları: ok, key_changed, rollback, fork, invalid, no_response, collector, records, head. Komut satırı, ortamdan; ortam ise dosyadan önceliklidir. Bilinmeyen seçenekler veya metin anahtarları, göz ardı edilmeyip bir mesajla tanığı durdurur. İfade biçimi doğrulamayı asla etkilemez: verify.py, her gönderimin sonunda imzalı belirteci kontrol eder. --post changes veya problems seçenekleriyle, gönderilmemiş kontroller yine de tanık günlüğünde bulunur ve verify.py bunları hiç gönderilmemiş olarak listeler; başlangıç kaydı politikayı belirtir. Her kontrol yine de günlüğünde görünür, bu nedenle daha az gönderim, Telegram tarafından tarihlendirilen sayının azalması anlamına gelir, kontrol sayısının azalması değil.

Kanal olmasa bile tanık, günlüğünü tutmaya devam eder. Tanık anahtarının parmak izini (python -m tgwitness.witness fingerprint) başka bir yerde saklayın.

Çeşitli çalışma alanları için herkese açık kanıt sayfası#

python -m tgwitness.proof Aynı anda en fazla 32 çalışma alanını izler ve her birinin en son imzalanmış kontrolünü içeren, salt okunur bir sayfa sunar. Her çalışma alanı, veri klasörü altında kendine ait bir tanık anahtarı ve günlüğü ile sabitlenmiş bir toplayıcı anahtarı alır; bir Telegram kanalına gönderim, çalışma alanı başına isteğe bağlıdır. Şu dosyadan başlayın: proof.config.example:

Alan Anlam
title Sayfa başlığı, 1–100 karakter
data_dir Dosyaya ilişkin Witness anahtarları ve günlükleri; varsayılan proof-data
interval, timeout Kontroller arasındaki süre (1–1440 dakika, varsayılan 5); bekleme süresi (5–600 saniye, varsayılan 20)
workspaces[].id, label Kısa küçük harfli takma ad ve gösterilen ad
workspaces[].collector Toplayıcı adresi; diğer çalışma alanlarının sonu /profiles/<workspace ID>
workspaces[].collector_fingerprint Zorunlu, her çalışma alanı için farklıdır
workspaces[].token_file Bu çalışma alanının salt okunur tanık jetonunu içeren dosya
workspaces[].channel, bot_token_file İsteğe bağlı, birlikte: her kontrolü bir kanala gönderin
workspaces[].proxy, bot_api İsteğe bağlı rota ve Bot API adresi
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790

İlk komut, bağlantı kurmadan dosyayı ve token dosyalarını doğrular. Sayfa yalnızca GET ve HEAD isteklerine yanıt verir:

  • / Tüm çalışma alanlarını gösterir; 2,5 aralık boyunca kontrol edilmeyen bir çalışma alanı, güncel olmayan olarak işaretlenir.
  • /api/proof JSON ile aynı sonucu döndürür.
  • /api/proof/<id> en son imzalanmış beyanı indirir (tgwitness-public-proof-v1): tanık kayıt numarası ve hash değeri, durum, sabitlenmiş toplayıcı anahtarı, kontrol noktası, toplama sayıcıları ve kanal gönderisinin başarılı olup olmadığı; söz konusu çalışma alanının tanık anahtarıyla imzalanmış.
  • /healthz Bir çalışma alanının monitörü durduğunda 503 hatası verir.

Sayfaya, Caddyfile.proof.example örneğindeki gibi kendine ait bir ana bilgisayar adı verin. Doğrulama için, bir çalışma alanının tanık günlüğünü python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip dışa aktarın ve aşağıda açıklandığı gibi kullanın.

Doğrula#

Tanık tarafında, günlüğünü dışa aktarın:

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 .

Ardından, herhangi bir yerden, toplayıcının imzalı ZIP dosyası ve genel kanalın adresi ile:

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 dışa aktarımını (Sohbet geçmişini dışa aktar → JSON, result.json dosyasını verir) veya sayfanın kaydedilmiş bir kopyasını da kabul eder; bunlar gönderi içeriğini kontrol eder ancak harici zaman bilgisi vermez.

verify.py, tanık günlüğünü (zincir ve imzalar) kontrol eder, ardından tanığın gördüğü her başlığın dışa aktarılan günlüğün bir parçası olup olmadığını kontrol eder: o sayımdaki kaydın tam olarak o hash değerine sahip olması gerekir. Eşleşmeyen bir başlık doğrulamayı geçemez — günlük, tanık tarafından görüldükten sonra değiştirilmiştir. Ayrıca, dışa aktarımdan sonra görülen başlıkları, tanığın kaydettiği anormallikleri, başarısız olan yanıtları, bu dışa aktarımda eşleşen kontrol noktalarının bulunduğu dönemleri ("X'ten Y'ye kadar tanıklandı") ve boşlukları rapor eder. Daha sonraki kontrol noktaları bu dönemleri uzatmaz. Sonuç, en son eşleşen kayıt numarasını ve eşleşen bir kontrol noktası olmayan sonraki kayıtların sayısını içerir. Yalnızca dışa aktarmanın kendi anahtarıyla imzalanmış yanıtlar sayılır: tanığın hiç görmediği bir anahtarla imzalanmış bir dışa aktarım, tanıklanmamış olarak rapor edilir ve --fingerprint seçeneği olmadan imzalayanın sabitlenmesi gerçekleşmez. --channel seçeneği ile her imzalı gönderi, tanık günlüğüyle kayıt bazında eşleşmelidir: değiştirilmiş gönderiler doğrulamayı geçemez, eksik gönderiler listelenir. Token’ın eşleşmesi içeriğin kimliğini doğrular; tarih, imzalı token’ın dışında yer alır.

Doğrulayıcı, canlı bir https://t.me/s/… veya https://telegram.me/s/… adresi ile doğrulama anında sayfadan her bir gönderinin tarihini okur. Telegram bu tarihi belirler; düzenlenmiş gönderilerin tarihleri kullanılmaz. Dışa aktarım başındaki bir gönderinin bu tür en erken tarihi, kanıt için asgari koşulu karşılayan son kaydın harici zamanıdır. Sağlanan result.json dosyası, kaydedilmiş bir sayfa veya başka bir web adresi gibi diğer kaynaklardan gelen tarihler, bağımsız zaman değil, sağlanan meta verilerdir; sonuç, gönderi tarihlerinin nereden geldiğini belirtir (post_date_verification).

Tanık eşliğinde dışa aktarma sınırı gerektirir#

Tanıkların da yer aldığı bir nihai kayıt içermesi gereken bir devir teslim işlemi için --require-witness'yi ekleyin:

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

Bu işlem, bağımsız olarak saklanan tanık parmak izini, toplayıcı anahtarından farklı bir anahtarı ve bu dışa aktarımın tam sonunda bulunan eşleşen bir kontrol noktasını gerektirir. Yalnızca daha önceki bir önek kapsayan bir kontrol noktası yetersizdir. Toplamayı duraklatın, tanığın son durumu gözlemlemesine izin verin ve günlüğe yeni yazma işlemleri yapılmadan dışa aktarım yapın; günlüğü değişirse, başka bir kontrol noktası saklayın ve o durumu dışa aktarın. Daha sonraki bir kontrol noktası tek başına, daha kısa bir dışa aktarımın son hash değerini doğrulayamaz. --channel da belirtildiğinde, eksik iddia edilen gönderiler veya boş bir eşleşme kümesi bu sıkı kontrolü geçemez. Bayrak olmadan, sıradan bütünlük kontrolleri, aksi takdirde sağlam olan bir arşivi reddetmeden tanık olmayan kayıtları yine de bildirir.

Tanık günlüğünü ve sabitlenmiş anahtarını ayrı tutun. Çevrimiçi kontroller, kontrol noktaları arasındaki sürekliliği doğrular; çevrimdışı doğrulama ise saklanan her kontrol noktasını dışa aktarılan verilerle karşılaştırır. Süreklilik kanıtı olmayan eski başlıklar, çevrimdışı karşılaştırmayı korur ve çevrimiçi süreklilik doğrulaması yapılmadan raporlanır. Rapor, tanığın hizmet dışı kalma sürelerini ve aralık bazında başarısız yayınları listeler.

Günlük mühürler ve kullanılamayan zaman damgası takvimleri#

Tanık, önceki UTC gününün günlük sınırını mühürler ve imzalanmış bu mührün hash değerini OpenTimestamps'a gönderir. Takvim gönderimi, bekleyen bir kanıttır; yalnızca bağımsız olarak kontrol edilmiş Bitcoin taahhütleri, doğrulayıcıda onay alır.

Tüm takvimler başarısız olursa, imzalı mühür ve başarısız deneme günlükte kalır. Saatlik bakım geçişi, yeniden başlatma veya tarih değişikliğinden sonra da dahil olmak üzere orijinal kaydı yeniden dener. Her geçişte en fazla 32 mührünü tarar, en fazla iki eksik gönderimi iletir ve her geçişte yeniden denemeler için en fazla 60 saniye harcar. Kalıcı bir imleç, eski mühürler arasında dönüşümlü olarak ilerler. Saklanan gönderimler, mevcut kanıt yükseltme yolunu izler.

Yeniden deneme, mührü yeniden yazmaz, orijinal tarihini değiştirmez veya takvimin onu daha önce aldığını iddia etmez. Daha geç bir Bitcoin taahhüdü, daha geç bir harici onay olarak kalır. Eksik kanıtlar none olarak kalır; bekleyen kanıtlar, doğrulayıcı bunları bağımsız olarak kontrol edene kadar pending olarak kalır.