Odniesienie / Dowody
Telegram · Niezależny świadek
Uruchom program Witness z własnym kluczem i botem, opublikuj podpisane punkty kontrolne na kanale i porównaj z nimi wyeksportowane dane.
TgWitness / Dokumentacja · Dowody i weryfikacja
Eksportowanie i weryfikacja · Wysoki poziom bezpieczeństwa · Przewodnik po panelach
Świadek przechowuje podpisane punkty kontrolne oddzielnie od kolektora. Sprawdza podpis kolektora i ciągłość dziennika, podpisuje wynik własnym kluczem i publikuje go na kanale Telegramu. Należy uruchomić go na oddzielnym serwerze z dostępem tylko do odczytu do punktu końcowego świadka kolektora.
Wynik techniczny obejmuje zachowane prefiksy dziennika, odpowiedzi na wyzwania, kontrole podpisów, kontrole włączenia i spójności Merkle oraz podpisane wyniki ciągłości. W przypadku świadka prowadzonego przez innego powiernika zachowaj dane powiernika i rejestr kontroli klucza wraz z jego odciskiem. Oddzielne klucze i oddzielne przechowywanie opisują różne części konfiguracji. Weryfikator podaje, że drugi klucz zachował głowę dziennika i do którego wpisu; rejestr kontroli klucza prowadzony przez powiernika pokazuje, kto przechowuje ten klucz. Dziennik świadka jest kontrolą pomocniczą; minimum dla dowodu to czas od strony trzeciej. Wpisy na kanale dodają czas zewnętrzny: Telegram datuje każdy publiczny wpis, a weryfikator sam odczytuje te daty.
Schemat w formie tekstowej
- Kolektor → Świadek (podpisany punkt kontrolny: liczba zapisów + skrót nagłówka)
- Świadek → Dziennik Witness, własny klucz
- Świadek → Kanał na Telegramie (podpisany wpis za pośrednictwem własnego bota)
- Plik ZIP z dowodami → verify.py
- Dziennik Witness, własny klucz → verify.py
- Kanał na Telegramie → verify.py (t.me/s – strona do przeglądania na żywo lub eksport na komputer stacjonarny)
Na tej stronie
Co przechowuje świadek#
| Świadek posiada | Świadek nigdy nie ma |
|---|---|
| Token świadka z prawem tylko do odczytu dla jednego obszaru roboczego | Sesja Telegramu użytkownika korzystającego z narzędzia lub dane uwierzytelniające do interfejsu API |
| Własny klucz Ed25519 i dziennik | Skarbiec kolektora, klucz podpisujący lub token panelowy |
| Własny token bota w serwisie Telegram | Treść wiadomości: nagłówek zawiera liczbę zapisów oraz skrót |
Token jest tworzony w sekcji Więcej narzędzi → Dodatki → Niezależny świadek, wyświetlany jednorazowo i przechowywany wyłącznie jako
SHA-256. Otwiera dokładnie jeden punkt końcowy, GET /api/witness/head, który zwraca świeżo
podpisany punkt kontrolny wraz z podpisanymi licznikami zbiorów bez treści oraz stanem operacyjnym.
Nie pozwala on na otwarcie panelu, odczytanie treści wiadomości ani zmianę ustawień, a
token panelu nie jest tam akceptowany. Token można unieważnić na tej samej stronie. Kolektor rejestruje
moment rozpoczęcia sprawdzania przez nowy klucz świadka (witness.seen) i pokazuje ostatnie sprawdzenie dla każdego tokenu;
świadek, który nie przeprowadził sprawdzenia w ciągu 2.5 interwałów, jest oznaczany jako przeterminowany.
Nowi świadkowie wysyłają losowe hasło weryfikacyjne przy każdej ankiecie; instrukcja przechwytywania powtarza je pod podpisem kolektora. Liczniki są powiązane z konkretnym punktem kontrolnym i są uwzględniane w podpisanych wpisach świadków. Starsze nagłówki są nadal akceptowane przez samodzielnego świadka. Sam wzrost objętości dziennika nigdy nie jest traktowany jako nowa wiadomość.
Co narzędzie sprawdza i rejestruje#
W każdym przedziale czasowym (domyślnie co 10 minut) narzędzie TgWitness:
- samodzielnie pobiera nagłówek (moduł zbierający nie może go przesłać ani pominąć);
- weryfikuje podpis kolektora, przypięty klucz kolektora (
--collector-fingerprint, lub pierwszy napotkany klucz), niezmniejszającą się liczbę oraz niezmienioną głowicę przy niezmienionej liczbie. Dowody włączenia i spójności Merkle'a weryfikują, czy rosnący dziennik rozszerza zachowany punkt kontrolny. Po wykorzystaniu dowodów ciągłości ich usunięcie jest odrzucane; - dodaje podpisany zapis do własnego dziennika:
witness.anchoro statusieok,key_changed,rollback(mniej zapisów niż poprzednio),fork(ta sama długość, inny nagłówek) lubinvalid(odpowiedź nie przeszła weryfikacji), albowitness.no_response, gdy moduł zbierający nie udzielił odpowiedzi; - wynik jest publikowany na kanale wraz z podpisem, w tym komunikat „brak odpowiedzi”, o ile narzędzie TgWitness
działa i ma dostęp do interfejsu API bota. Rejestrowany jest identyfikator publikacji (
witness.posted), a także identyfikator nieudanej publikacji (witness.post_failed).
Wpis wygląda następująco; ostatnia linia zawiera podpisane oświadczenie:
TgWitness witness #42 · journal head
Collector 3fa9c2d1e0b4a7f6: 18234 records
Head 9b1f…c07e
2026-10-28T19:40:00.123+00:00
TGW1.eyJhdCI6…<statement>.<signature>
Uruchom program Witness#
Potrzebny jest Państwu bot w Telegramie (można go utworzyć za pomocą @BotFather), kanał, w którym bot ten pełni funkcję administratora, oraz adres kolektora dostępny dla świadka — za pośrednictwem protokołu HTTPS poza siecią prywatną (patrz profil HTTPS w sekcji wdrożenia).
W panelu otwórz Więcej narzędzi → Dodatki → Niezależny świadek → Konfiguruj
. Trzy kroki obejmują
dostęp tylko do odczytu, Twój kanał i interwał, a następnie uruchomienie świadka. Polityka
publikacji, opcjonalny serwer proxy HTTP/SOCKS5 oraz niestandardowy adres API bota znajdują się w ustawieniach zaawansowanych
. Formularz
pobiera plik witness.json
z przypiętym kluczem kolektora tego obszaru roboczego. Pobierz nowo
utworzony token tylko do odczytu, wybierając opcję „Zapisz plik dostępu
jako” witness-token.txt
; umieść go oraz plik bot-token.txt
utworzony na hoście świadka obok tego pliku JSON. Kolektor nigdy nie otrzymuje tokenu bota.
Pobieranie nie uruchamia usługi ani nie publikuje wiadomości. Żaden świadek projektu hostowanego nie jest
domyślnie rejestrowany.
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
Pierwsze polecenie sprawdza pliki konfiguracyjne i pliki tajne bez wysyłania żądań sieciowych ani tworzenia kluczy. Ścieżki w formacie JSON są względne względem tego pliku; ścieżki CLI/środowiska są względne względem katalogu roboczego. Należy zachować odcisk palca świadka poza jego hostem. Wskaźnik ostatniego odczytu kolektora potwierdza jedynie żądanie; publikacja jest zgłaszana przez Proof lub sprawdzana w dzienniku świadka oraz na kanale.
Jeśli panel znajduje się za tunelem SSH, należy udostępnić wyłącznie wyznaczony punkt końcowy Witness na
oddzielnej nazwie hosta HTTPS, korzystając z poniższego przykładu wykorzystującego Caddy.
Domyślny obszar roboczy korzysta wówczas z https://witness.example.org, pozostałe obszary robocze – z
https://witness.example.org/profiles/ID. Tokeny są nadal wymagane; panel oraz jego
inne trasy API nie są przekierowywane przez ten wirtualny host.
Proszę wybrać opcję all, aby uzyskać regularnie publikowane punkty kontrolne. Pięciominutowy interwał oznacza około 288
wpisów dziennie na każdy obszar roboczy. Opcje changes i problems celowo pomijają publikację niektórych punktów kontrolnych.
MTProxy jest przeznaczony dla klienta Telegramu służącego do gromadzenia danych. Polling HTTP serwisu Witness oraz interfejs API botów Telegramu HTTPS
korzystają z własnej trasy bezpośredniej/HTTP/SOCKS5 (Bot API).
Obok modułu zbierającego, z wykorzystaniem Docker (ten sam host — niezależny proces i klucz, ale ten
sam operator): należy wprowadzić wartości w polu „.env” i uruchomić profil.
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
W przypadku publikacji obrazu prosimy o użycie kodu docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d.
Na serwerze innej osoby (oddzielne przechowywanie): skopiuj tam repozytorium, ustaw
TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org oraz trzy powyższe wartości
w pliku .env, a następnie
docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d
lub bez wykorzystania 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
Opublikuj na Discordzie#
Świadek może publikować posty na kanale Discord zamiast w Telegramie. W Discordzie otwórz
Edytuj kanał → Integracje → Webhooki, utwórz webhook i skopiuj jego adres URL. W
panelu wybierz Webhook Discorda · twój kanał w kroku 2. Na serwerze świadka
zapisz adres URL jako discord-webhook.txt obok witness.json; nigdy nie trafia do
kolektora.
python -m tgwitness.witness run --collector https://your-collector.example.org \
--token-file witness-token.txt --discord-webhook-file discord-webhook.txt
Świadek ma jednego wydawcę: kanał Telegramu lub webhook Discorda, ale nie oba jednocześnie. Posty
zawierają to samo podpisane oświadczenie i nie mogą wysyłać powiadomień do nikogo. Post dłuższy niż
2,000
znaków w Discordzie jest zastępowany krótką linią z pełną weryfikacją dołączoną jako
witness-check.txt
. Każdy identyfikator posta jest rejestrowany jako witness.posted
. verify.py --channel
odczytuje wyłącznie kanały Telegramu, więc w przypadku Discorda należy prowadzić dziennik świadka: zawiera on każdą
weryfikację. Posty na Discordzie nie dostarczają weryfikatorowi żadnego czasu zewnętrznego.
Opcje#
| Opcja | Środowisko | Domyślnie | Znaczenie |
|---|---|---|---|
--interval |
TGWITNESS_WITNESS_INTERVAL |
10 | Czas między kolejnymi sprawdzeniami: 1–1440 |
--timeout |
_TIMEOUT |
30 | Czas oczekiwania na uruchomienie modułu zbierającego dane i interfejsu API bota: od 5 do 600 sekund |
--post |
_POST |
all |
all: wszystko w porządku; changes: nowa kwestia lub problem; problems: same problemy i brak odpowiedzi |
--title |
_TITLE |
TgWitness witness |
Pierwsze słowa każdego wpisu na kanale |
--collector-fingerprint |
_COLLECTOR_FINGERPRINT |
– | Należy zapisać klucz kolektora zamiast polegać na pierwszej odpowiedzi |
--proxy |
_PROXY |
bezpośredni | socks5://host:port lub http://host:port |
--bot-api |
_BOT_API |
https://api.telegram.org |
Adres interfejsu API bota, np. lokalny serwer interfejsu API bota |
--data-dir |
_DATA |
witness-data |
Klucz Witness i dziennik |
--config |
_CONFIG |
– | Plik JSON zawierający dowolną z powyższych opcji |
Adres kolektora, tokeny i kanał pochodzą z --collector, --token lub
--token-file, --bot-token lub --bot-token-file, --discord-webhook-file oraz --channel,
lub _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE,
_DISCORD_WEBHOOK_FILE oraz _CHANNEL, co sprawia, że sekrety nie pojawiają się na liście procesów.
Plik konfiguracyjny wykorzystuje nazwy opcji z podkreśleniami oraz symbol texts, który zastępuje słowa
w postach kanału:
{"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"}}
Klucze texts: ok, key_changed, rollback, fork, invalid, no_response, collector,
records, head. Wiersz poleceń ma pierwszeństwo przed środowiskiem, a środowisko przed plikiem.
Nieznane opcje lub klucze tekstowe powodują zatrzymanie działania świadka wraz z wyświetleniem komunikatu, zamiast być ignorowane.
Sformułowanie nigdy nie wpływa na weryfikację: verify.py sprawdza podpisany token na końcu każdego
wpisu. W przypadku opcji --post changes lub problems sprawdzania, które nie zostały opublikowane, nadal znajdują się w
dzienniku świadków, a verify.py wymienia je jako nigdy nieopublikowane; rekord początkowy określa
politykę. Każde sprawdzenie nadal pojawia się w dzienniku, więc mniejsza liczba wpisów oznacza mniejszą liczbę dat
nadanych przez Telegram, a nie mniejszą liczbę sprawdzeń.
Nawet bez kanału aplikacja TgWitness nadal prowadzi swój dziennik. Proszę przechowywać odcisk klucza aplikacji TgWitness
(python -m tgwitness.witness fingerprint) w innym miejscu.
Publiczna strona z dowodami dla kilku obszarów roboczych#
python -m tgwitness.proof Obsługuje do 32 obszarów roboczych jednocześnie i udostępnia stronę tylko do odczytu
z najnowszym podpisanym raportem dla każdego z nich. Każdy obszar roboczy otrzymuje własny klucz świadka oraz
dziennik w folderze danych, a także przypięty klucz kolektora; publikowanie na kanale Telegramu
jest opcjonalne dla każdego obszaru roboczego. Zacznij od pliku
proof.config.example:
| Dziedzina | Znaczenie |
|---|---|
title |
Tytuł strony, 1–100 znaków |
data_dir |
Klucze i dzienniki Witness, powiązane z plikiem; domyślnie proof-data |
interval, timeout |
Czas w minutach między sprawdzaniami (1–1440, domyślnie 5); czas oczekiwania w sekundach (5–600, domyślnie 20) |
workspaces[].id, label |
Krótki alias pisany małymi literami oraz nazwa wyświetlana |
workspaces[].collector |
Adres kolektora; nazwy pozostałych obszarów roboczych kończą się na /profiles/<workspace ID> |
workspaces[].collector_fingerprint |
Wymagane, różne dla każdego obszaru roboczego |
workspaces[].token_file |
Plik zawierający token świadka tego obszaru roboczego z prawem tylko do odczytu |
workspaces[].channel, bot_token_file |
Opcjonalnie, łącznie: publikuj każdy wpis na kanale |
workspaces[].proxy, bot_api |
Opcjonalna trasa i adres API bota |
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790
Pierwsze polecenie weryfikuje plik oraz pliki tokenów bez nawiązywania połączenia. Strona obsługuje wyłącznie żądania GET i HEAD:
/wyświetla wszystkie obszary robocze; obszar roboczy, który nie został zaznaczony przez 2,5 interwału, jest oznaczany jako nieaktualny./api/proofzwraca to samo co JSON./api/proof/<id>pobiera najnowsze podpisane oświadczenie (tgwitness-public-proof-v1): numer i skrót zapisu świadka, status, przypięty klucz zbierającego, punkt kontrolny, liczniki zbiorów oraz informacja, czy publikacja na kanale zakończyła się powodzeniem, podpisane kluczem świadka danego obszaru roboczego./healthzzwraca kod 503, gdy monitor obszaru roboczego przestał działać.
Nadaj stronie własną nazwę hosta, np.
Caddyfile.proof.example. W celu weryfikacji wyeksportuj
dziennik świadectw obszaru roboczego,
python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip i wykorzystaj go
zgodnie z poniższym opisem.
Zweryfikuj#
Ze strony świadka należy wyeksportować ten dziennik:
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 .
Następnie, w dowolnym miejscu, korzystając z podpisanego pliku ZIP kolektora oraz adresu kanału publicznego:
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 akceptuje również eksport z aplikacji Telegram Desktop (Eksportuj historię czatu → JSON daje plik
result.json) lub zapisaną kopię strony; sprawdzają one treść wpisu, ale nie podają
czasu zewnętrznego.
verify.py sprawdza dziennik świadka (łańcuch i podpisy), a następnie czy każdy nagłówek, który
widział świadek, znajduje się w wyeksportowanym dzienniku: rekord o tym numerze musi mieć dokładnie
ten sam skrót. Głowa, która nie pasuje, nie przechodzi weryfikacji — dziennik został zmieniony po tym, jak
świadek go zobaczył. Zgłasza również głowy zaobserwowane po eksporcie, anomalie zarejestrowane przez świadka,
nieudane odpowiedzi, okresy, dla których w tym eksporcie występują pasujące punkty kontrolne
(„Świadczone od X do Y”) oraz luki. Późniejsze punkty kontrolne nie przedłużają tych okresów.
Wynik zawiera numer ostatniego dopasowanego rekordu oraz liczbę kolejnych rekordów
bez pasującego punktu kontrolnego. Liczą się wyłącznie odpowiedzi podpisane kluczem należącym do danego eksportu: eksport podpisany
kluczem, którego świadek nigdy nie widział, jest zgłaszany jako niepotwierdzony, a bez opcji --fingerprint jego
podpisujący pozostaje nieprzypisany. Przy użyciu opcji --channel każdy podpisany wpis musi zgadzać się z dziennikiem świadka
wpis po wpisie: zmienione wpisy nie przechodzą weryfikacji, a brakujące wpisy są wymienione. Dopasowanie
tokenu uwierzytelnia treść; data nie jest częścią podpisanego tokenu.
W przypadku aktywnego adresu https://t.me/s/… lub https://telegram.me/s/… weryfikator odczytuje
datę każdego wpisu ze strony w momencie weryfikacji. Telegram ustala tę datę; daty
edytowanych postów nie są brane pod uwagę. Najwcześniejsza taka data postu na początku eksportu stanowi czas zewnętrzny
dla ostatniego rekordu, który spełnia warunek minimalnego wymogu dowodowego. Daty
pochodzące z jakiegokolwiek innego źródła, takiego jak dostarczony plik result.json, zapisana strona lub inny adres
internetowy, stanowią metadane, a nie niezależny czas; wynik wskazuje, skąd pochodzą daty
postów (post_date_verification).
Wymagany jest eksport z potwierdzeniem#
W przypadku przekazania, które musi obejmować poświadczony ostateczny zapis, proszę dodać --require-witness:
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
--witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness
Wymaga to niezależnie przechowywanego odcisku palca świadka, klucza innego niż
klucz kolektora oraz pasującego punktu kontrolnego dokładnie na końcu tego eksportu. Punkt kontrolny
obejmujący jedynie wcześniejszy prefiks jest niewystarczający. Należy wstrzymać gromadzenie danych, pozwolić świadkowi
na obserwację stanu końcowego i przeprowadzić eksport przed dalszym zapisywaniem w dzienniku; jeśli dziennik ulegnie zmianie, należy zachować kolejny punkt kontrolny i
wyeksportować ten stan. Sam późniejszy punkt kontrolny nie pozwala zweryfikować końcowego skrótu krótszego eksportu.
Gdy podano również opcję --channel, brakujące zgłoszone wpisy lub pusty zestaw dopasowań powodują niepowodzenie tej
ścisłej kontroli. Bez tej flagi zwykłe kontrole integralności nadal zgłaszają rekordy bez świadków,
nie odrzucając jednak archiwum, które poza tym jest nienaruszone.
Dziennik świadka i jego przypięty klucz należy przechowywać oddzielnie. Kontrole online weryfikują ciągłość między punktami kontrolnymi; weryfikacja offline porównuje każdy zachowany punkt kontrolny z eksportem. Starsze nagłówki bez dowodów ciągłości zachowują porównanie offline i są raportowane bez weryfikacji ciągłości online. Raport zawiera listę przestojów świadka oraz nieudanych publikacji w podziale na przedziały czasowe.
Codzienne pieczęcie i niedostępne kalendarze znaczników czasu#
Świadek pieczętuje granicę dziennika z poprzedniego dnia UTC i przesyła skrót tej podpisanej pieczęci do serwisu OpenTimestamps. Zgłoszenie kalendarzowe jest dowodem oczekującym na zatwierdzenie; tylko niezależnie sprawdzone zobowiązania Bitcoin otrzymują potwierdzenie w weryfikatorze.
Jeśli wszystkie kalendarze zawiodą, podpisana pieczęć i nieudana próba pozostają w dzienniku. Godzinny cykl konserwacyjny ponawia próbę dla tego oryginalnego zapisu, w tym po ponownym uruchomieniu lub zmianie daty. Skanuje maksymalnie 32 pieczęci, przesyła maksymalnie dwa brakujące zgłoszenia i poświęca maksymalnie 60 sekund na ponowne próby w każdym cyklu. Trwały kursor przechodzi kolejno przez starsze pieczęcie. Zachowane zgłoszenia podążają za istniejącą ścieżką aktualizacji dowodów.
Ponowna próba nie powoduje przepisania pieczęci, zmiany jej pierwotnej daty ani twierdzenia, że
kalendarz otrzymał ją wcześniej. Późniejsze zobowiązanie Bitcoin pozostaje późniejszym zewnętrznym
potwierdzeniem. Brakujące dowody pozostają na poziomie none; dowody oczekujące pozostają na poziomie pending, dopóki
weryfikator nie sprawdzi ich niezależnie.