Softech zaprojektował dla klienta objętego NDA natywną infrastrukturę do przyjmowania płatności stablecoin przez dedykowane adresy blockchain. Rozwiązanie nie traktuje transferu on-chain jako gotowego salda użytkownika: najpierw adres jest przypisany do kontekstu biznesowego, następnie observer wykrywa zdarzenie, system waliduje sieć, token i kwotę, confirmation engine czeka na przyjętą finalność, a dopiero potem wewnętrzny ledger stosuje skutek biznesowy. Sweeping i treasury działają osobno, dzięki czemu awaria operacji wewnętrznej nie unieważnia poprawnie zaksięgowanej płatności.
Kontekst biznesowy i sytuacja przed wdrożeniem
W tym produkcie płatność blockchain była częścią core domain, a nie dodatkiem checkoutowym. System musiał jednoznacznie identyfikować wpłaty użytkowników i obsługiwać je automatycznie bez polegania na ręcznym sprawdzaniu explorerów lub wspólnego adresu treasury.
- Adres płatniczy musiał być powiązany z użytkownikiem, kontem lub konkretnym payment intent.
- Transfer należało zweryfikować na poziomie network, token contract, destination i amount.
- System musiał odróżniać wykrycie transakcji od jej finalnego uznania w produkcie.
- Środki po zaksięgowaniu miały trafiać do osobnego workflow treasury bez zmiany historii użytkownika.
Stan wyjściowy
Najprostszy wariant — jeden wspólny wallet i ręczne sprawdzanie transakcji — nie skaluje się operacyjnie i nie zapewnia jednoznacznego przypisania transferu do zobowiązania. Równie ryzykowne jest księgowanie salda produktu wyłącznie na podstawie bieżącego blockchain balance.
- Wspólny adres utrudnia jednoznaczne przypisanie transferu do właściciela i celu płatności.
- RPC lub indexer może mieć chwilową przerwę, dlatego observer musi umieć odtwarzać brakujące bloki.
- Transfer może być poprawny technicznie, ale niezgodny z oczekiwanym tokenem, siecią lub kwotą.
- Ruch treasury po płatności jest innym procesem niż uznanie zobowiązania użytkownika.
Cele, kryteria sukcesu i ograniczenia
Discovery objęło model adresów, lifecycle payment intent, politykę finalności, źródła danych blockchain, wymagania replay, klasyfikację błędnych transferów oraz granice pomiędzy customer ledger i treasury. Kluczową decyzją było potraktowanie blockchaina jako źródła zdarzeń, a nie księgi produktu.
Cele produktu
- Przypisywać dedykowane adresy do kontekstu biznesowego bez ujawniania kluczy prywatnych warstwie aplikacji.
- Wykrywać transfery stablecoin z możliwością replay i bez podwójnego przetwarzania.
- Walidować network, token contract, destination, amount oraz politykę finalności.
- Księgować płatność w wewnętrznym ledgerze niezależnym od blockchain balance.
- Oddzielić treasury sweeping od customer payment lifecycle i zapewnić obsługę wyjątków.
Kryteria sukcesu
- Każdy obserwowany transfer ma deterministyczny klucz zdarzenia i może być bezpiecznie przetworzony ponownie.
- Produkt nie kredytuje płatności przed spełnieniem polityki potwierdzeń i walidacji tokenu.
- Awaria RPC lub indexera nie powoduje trwałej utraty zdarzenia płatniczego.
- Sweep failure nie cofa prawidłowo zaksięgowanej płatności użytkownika.
- Operator może rozróżnić underpayment, overpayment, wrong token, wrong network i manual review.
NDA i bezpieczeństwo kluczy
Nie ujawniamy dokładnego custody model, derivation path, adresów, providerów kluczy ani produkcyjnych parametrów bezpieczeństwa.
Asynchroniczna finalność
Wykrycie transferu nie oznacza automatycznie, że produkt powinien natychmiast uznać saldo użytkownika.
Wiele źródeł awarii
RPC, indexer, kolejka, baza danych i sweep service mogą chwilowo działać niezależnie lub być niedostępne.
Rozdzielenie custody i aplikacji
Warstwa produktu nie powinna posiadać bezpośredniego dostępu do kluczy umożliwiających swobodne transfery treasury.
Analiza i decyzje produktowe
- Zdefiniowaliśmy właściciela i lifecycle dedykowanego adresu płatniczego.
- Ustaliliśmy deterministic event identity na podstawie transakcji, log index i network context.
- Określiliśmy checkpointing oraz zakres bezpiecznego block replay.
- Rozpisaliśmy stany DETECTED, CONFIRMING, CONFIRMED, CREDITED oraz wyjątki.
- Oddzieliliśmy payment acceptance od sweep i późniejszego zarządzania treasury.
Architektura rozwiązania
System składa się z address allocation i wallet registry, blockchain observera z checkpointingiem, validation i confirmation engine, event store, internal ledger oraz oddzielnego sweep/treasury pipeline. Projekt został ułożony tak, aby każda warstwa mogła zostać odtworzona i ponowiona bez podwójnego kredytowania płatności.
- 01Warstwa 01
Address allocation i wallet registry
Dedykowany adres otrzymuje jawne powiązanie z użytkownikiem, kontem lub payment intent oraz stan lifecycle.
Dedicated addressesWallet registry - 02Warstwa 02
Blockchain observer
Observer czyta bloki i eventy tokenów, zapisuje checkpointy i może bezpiecznie odtworzyć zakres po awarii źródła danych.
RPC / indexerCheckpointingReplay - 03Warstwa 03
Validation i confirmation engine
Warstwa weryfikuje network, token contract, destination, amount oraz przyjętą politykę potwierdzeń przed dalszym kredytowaniem.
Token validationFinality policyState machine - 04Warstwa 04
Blockchain event store i internal ledger
Raw blockchain event zostaje zachowany jako dowód, a zaakceptowany payment event tworzy kontrolowany wpis w ledgerze produktu.
Event storeInternal ledgerIdempotency - 05Warstwa 05
Sweep, treasury i operations
Po zaksięgowaniu płatności środki mogą zostać przeniesione zgodnie z polityką treasury, a wyjątki trafiają do kontrolowanej obsługi operatorskiej.
Sweep serviceTreasury workflowOperational review
Problemy, decyzje i wdrożone możliwości
Jeden wspólny adres nie identyfikowałby jednoznacznie właściciela wpłaty.
Adresy są przydzielane i rejestrowane w kontekście konkretnego użytkownika lub payment intent.
Deterministyczne przypisanie wpłaty
Transfer może zostać powiązany z właściwą domeną bez zgadywania na podstawie kwoty lub komentarza.
Awaria źródła danych mogłaby spowodować pominięcie bloku.
Observer zapisuje checkpoint i pozwala na bezpieczny replay zakresu.
Recoverable chain observation
Po przywróceniu źródła system może nadrobić zdarzenia bez podwójnego kredytowania.
Sam transfer tokenu nie gwarantuje zgodności z oczekiwaną płatnością.
Przed uznaniem sprawdzamy network, token contract, destination, amount i finality.
Validated payment acceptance
Wrong token, wrong network i niezgodne kwoty nie trafiają automatycznie do poprawnego salda użytkownika.
Blockchain balance nie odzwierciedla zobowiązań i historii produktu.
Za źródło stanu biznesowego przyjęliśmy niezależny internal ledger.
Product ledger independent of chain balance
Saldo produktu zachowuje historię i semantykę domenową niezależnie od późniejszych ruchów treasury.
Sweep do treasury może nie udać się mimo poprawnej płatności klienta.
Customer credit i sweep są osobnymi state machines i retry policies.
Decoupled treasury operations
Awaria wewnętrznego transferu nie cofa poprawnie potwierdzonej płatności użytkownika.
Decyzje technologiczne
| Technologia | Rola | Uzasadnienie | Konsekwencja wyboru |
|---|---|---|---|
| Dedicated deposit addresses | Identyfikacja wpłat | Adres staje się stabilnym kluczem routingu transferu do konkretnego kontekstu biznesowego. | Większa liczba adresów zwiększa wymagania registry, monitoring i polityki custody. |
| RPC / indexer observer | Źródło zdarzeń blockchain | Pozwala automatycznie wykrywać token transfers oraz odbudowywać historię z bloków. | Wymaga redundancji lub strategii recovery na wypadek błędnych lub niedostępnych źródeł. |
| Checkpoint + replay | Odtwarzalność | System zna ostatni przetworzony zakres i może powtórzyć skanowanie po awarii. | Replay musi być w pełni idempotentny i wydajny dla większych zakresów. |
| Confirmation engine | Finalność | Oddziela DETECTED od CONFIRMED i pozwala dostosować politykę do sieci oraz ryzyka produktu. | Większa ostrożność zwiększa czas oczekiwania użytkownika. |
| Internal ledger | Stan biznesowy | Zachowuje zobowiązania i historię niezależnie od bieżących sald blockchain oraz treasury. | Wymaga jawnej synchronizacji i reconciliation z warstwą on-chain. |
| Sweep service | Treasury movement | Pozwala konsolidować środki lub realizować politykę treasury bez obciążania customer payment lifecycle. | Wprowadza osobny obszar fee management, nonce management i retry. |
Integracje i przepływy danych
Blockchain RPC / indexer
Chain → observerDostarcza bloki, logi i token transfer events do warstwy wykrywania.
Checkpointing i replay ograniczają ryzyko utraty zdarzeń przy chwilowej awarii źródła.
Wallet / custody layer
Allocator ↔ wallet layerUdostępnia adresy płatnicze i kontrolowany mechanizm wykonywania późniejszych transferów bez ekspozycji kluczy do domeny produktu.
Publiczny opis nie ujawnia konkretnego modelu custody ani schematu kluczy.
Treasury operations
Ledger → sweep / treasuryUruchamia wewnętrzny transfer środków dopiero po prawidłowym uznaniu zdarzenia płatniczego.
Sweep ma oddzielny status i retry, więc jego awaria nie zmienia customer payment status.
AI, bezpieczeństwo i niezawodność
Brak kluczy prywatnych w domenie produktu
Logika aplikacji operuje identyfikatorami walletów i zleceniami, a nie surowymi sekretami podpisującymi.
Deterministyczna tożsamość eventu
Każdy event blockchain otrzymuje stabilną tożsamość, aby replay i wiele źródeł nie powodowały duplikacji.
Checkpointing i backfill
Observer zapisuje postęp i pozwala kontrolowanie odtworzyć brakujące bloki.
Oddzielne state machines
Customer payment, confirmation i treasury movement nie są jednym statusem, dzięki czemu awaria downstream nie cofa poprawnej wpłaty.
Manual review zamiast automatycznego zgadywania
Nieprawidłowe lub niejednoznaczne transfery są klasyfikowane do obsługi, zamiast zmieniać saldo na podstawie heurystyki.
Realizacja, testy i uruchomienie
- 1Faza 1 / Wallet domain
Zdefiniować właściciela adresu, lifecycle allocation i granicę custody.
- Wallet registry
- Address allocation rules
- Custody boundary contract
Rezultat: Adresy otrzymały jawne relacje do kontekstu biznesowego bez przenoszenia sekretów do aplikacji.
- 2Faza 2 / Chain observation
Wykrywać transfery z checkpointingiem, replay i deterministic event identity.
- RPC/indexer adapter
- Checkpoint store
- Replay and deduplication
Rezultat: Warstwa obserwacji może nadrobić brakujące zdarzenia i bezpiecznie przetworzyć je ponownie.
- 3Faza 3 / Validation and ledger
Rozdzielić wykrycie, potwierdzenie i końcowe uznanie płatności w produkcie.
- Token/network validation
- Confirmation state machine
- Internal ledger entries
Rezultat: Product balance powstaje dopiero po spełnieniu warunków płatności i zachowuje własną historię.
- 4Faza 4 / Treasury and operations
Dodać sweep workflow, retry, monitoring i ręczną obsługę niejednoznacznych zdarzeń.
- Sweep state machine
- Treasury reconciliation
- Operations exception queue
Rezultat: Ruch środków i wyjątki zostały oddzielone od core customer payment lifecycle.
Replay tego samego zakresu bloków
Ponowne skanowanie nie może ponownie utworzyć payment credit dla już przetworzonego eventu.
Wrong token / wrong network
Transfer do znanego adresu, ale niespełniający warunków aktywa lub sieci, trafia do wyjątku zamiast do poprawnego salda.
Underpayment i overpayment
Kwoty różne od oczekiwanej nie są automatycznie normalizowane bez jawnej polityki produktu.
RPC outage and catch-up
Po kontrolowanej przerwie observer wraca do checkpointu i uzupełnia brakujące zdarzenia.
Sweep failure
Nieudany transfer treasury pozostaje retryable i nie zmienia statusu poprawnie zaksięgowanej płatności klienta.
Co potwierdza opis projektu
Case study nie publikuje wolumenów on-chain, liczby adresów ani danych treasury. Jako rezultat techniczny opisujemy sprawdzalne właściwości architektury: deterministyczne przypisanie, replay, walidację, kontrolowaną finalność, niezależny ledger oraz rozdzielenie customer payment od treasury operations.
| Zakres | Podstawa | Materiał | Potwierdzenie | Granice wniosku |
|---|---|---|---|---|
| Dedykowany adres jest powiązany z kontekstem biznesowym przed przyjęciem transferu. | Diagram architektury walletów | CW-01 · materiał projektowy i architektura wdrożenia | Potwierdzone operacyjnie | Publiczny diagram nie ujawnia derivation ani modelu custody. |
| Wykrycie transferu i końcowe uznanie płatności są oddzielnymi stanami. | Diagram observera i potwierdzeń | CW-02 · materiał projektowy i architektura wdrożenia | Potwierdzone operacyjnie | Dokładne progi finalności dla sieci produkcyjnych pozostają poufne. |
| Observer może odtworzyć zakres bloków dzięki checkpointingowi i idempotentnemu replay. | Diagram observera i potwierdzeń | CW-02 · materiał projektowy i architektura wdrożenia | Potwierdzone operacyjnie | Nie publikujemy topologii dostawców RPC ani konfiguracji redundancji. |
| Product ledger jest niezależny od blockchain balance i późniejszego sweepingu. | Diagram ledger i treasury | CW-03 · materiał projektowy i architektura wdrożenia | Potwierdzone operacyjnie | Publiczna wersja nie pokazuje wewnętrznego schematu księgowego klienta. |
| Sweep do treasury jest osobnym workflow z własnym stanem i retry. | Diagram ledger i treasury | CW-03 · materiał projektowy i architektura wdrożenia | Potwierdzone operacyjnie | Adresy treasury i reguły fee management pozostają poufne. |
| Wrong token, wrong network i niezgodna kwota są klasyfikowane przed zaksięgowaniem. | Diagram observera i potwierdzeń | CW-02 · materiał projektowy i architektura wdrożenia | Potwierdzone operacyjnie | Publiczny diagram pokazuje klasy wyjątków, a nie dokładne reguły ryzyka klienta. |
Jak czytać te informacje
- Nie publikujemy liczby adresów ani aktywnych walletów.
- Nie publikujemy dokładnych sieci produkcyjnych, progów finalności ani wolumenów transferów.
- Nie publikujemy modelu custody, providerów kluczy ani adresów treasury.
- Efekty są opisane jako system capabilities, nie jako procentowe KPI biznesowe.
Zmiana procesu, konsekwencje decyzji i wnioski
| Obszar | Przed wdrożeniem | Po wdrożeniu | Wpływ biznesowy |
|---|---|---|---|
| Identyfikacja wpłaty | Wspólny adres wymagałby dodatkowych heurystyk lub ręcznego przypisania. | Dedykowany adres ma jawnego właściciela i kontekst payment intent. | Transfer może zostać automatycznie przypisany do właściwej domeny. |
| Wykrywanie blockchain | Brak zdarzenia w czasie awarii RPC mógłby pozostać niezauważony. | Checkpointing i replay pozwalają ponownie przeskanować zakres. | System może odtworzyć stan bez ręcznego dodawania transakcji. |
| Finalność | Wykryty transfer mógłby zostać uznany zbyt wcześnie. | Confirmation engine oddziela DETECTED, CONFIRMING, CONFIRMED i CREDITED. | Polityka ryzyka jest jawna i kontrolowana. |
| Saldo produktu | Blockchain balance miesza środki techniczne z logiką zobowiązań użytkowników. | Internal ledger zachowuje stan domenowy niezależnie od położenia środków. | Treasury może się zmieniać bez zmiany historii klienta. |
| Treasury | Konsolidacja środków byłaby częścią tej samej ścieżki co customer payment. | Sweep działa jako osobny retryable workflow. | Awaria treasury nie unieważnia prawidłowej wpłaty. |
Dedykowane adresy
- Alternatywa
- Jeden wspólny adres
- Konsekwencja
- Większa liczba obiektów walletowych i większy koszt operacyjny registry.
- Uzasadnienie
- Deterministyczne przypisanie płatności jest ważniejsze niż prostota jednego adresu.
Checkpointed observer
- Alternatywa
- Wyłącznie realtime websocket
- Konsekwencja
- Więcej logiki przetwarzania i storage dla checkpointów.
- Uzasadnienie
- System może nadrobić przerwę i nie zależy od ciągłości pojedynczego połączenia.
Internal ledger
- Alternatywa
- Blockchain jako jedyne źródło salda
- Konsekwencja
- Dodatkowa warstwa reconciliation i danych.
- Uzasadnienie
- Pozwala zachować semantykę zobowiązań, refundów i historii produktu.
Oddzielny sweep workflow
- Alternatywa
- Natychmiastowy sweep przed uznaniem płatności
- Konsekwencja
- Więcej stanów operacyjnych i retry.
- Uzasadnienie
- Customer payment nie jest blokowany przez operację treasury, która może zawieść niezależnie.
Najważniejsze lekcje
- Adres blockchain jest identyfikatorem technicznym; payment intent nadaje mu sens biznesowy.
- Observer musi być projektowany pod replay od pierwszego dnia, bo realtime event stream nie jest gwarancją kompletności.
- Blockchain event i product ledger entry powinny mieć jawne, audytowalne powiązanie, ale nie być tym samym rekordem.
- Finality policy jest częścią produktu i ryzyka, a nie przypadkową wartością confirmations w kodzie.
- Treasury jest downstream procesem; nie powinien decydować o tym, czy poprawna płatność klienta istnieje.
Dla jakich organizacji ten model jest istotny
FinTech i account-based products
Gdy wpłaty stablecoin zasilają konto użytkownika lub wpływają na core balance produktu.
Marketplace i platformy wielostronne
Gdy system musi rozróżniać wielu płatników, beneficjentów i przepływy treasury.
Produkty z własnym treasury workflow
Gdy środki po wpłacie wymagają konsolidacji, alokacji lub innych operacji wewnętrznych.
Systemy wymagające kontroli on-chain
Gdy managed gateway nie daje wystarczającej kontroli nad adresami, identyfikacją transferów lub stanem produktu.
Powiązana wiedza i usługi
Crypto Wallet Development
BOFU path dla embedded/programmatic wallets, MPC, deposit addresses i treasury operations.
Crypto & Stablecoin Payment Systems
Usługa obejmująca custom wallet infrastructure, monitoring on-chain, ledger i treasury.
Digital Assets & Blockchain
Hub usług blockchain i infrastruktury aktywów cyfrowych Softech.
Smart Contract Development
Powiązana kompetencja dla produktów łączących payments z programowalną logiką on-chain.
USDC + CoinGate managed settlement
Alternatywny model korzystający z managed payment providera zamiast własnej warstwy walletowej.
Node.js
Backend event processing, kolejki i integracje dla systemów transakcyjnych.
API Engineering
Kontrakty pomiędzy wallet layer, observerem, ledgerem, treasury i produktem.
Potrzebujesz natywnego payment railu zamiast gotowego gatewaya?
Zaprojektujemy wallet allocation, blockchain observation, confirmation policy, internal ledger, reconciliation, sweep i treasury tak, aby płatność była częścią domeny produktu, a nie tylko transferem do adresu.
Najważniejsze potwierdzone fakty
Poniższe informacje podsumowują potwierdzony zakres produktu i nie zawierają niezatwierdzonych danych o wzroście.
- 1
Projekt klienta objęty jest NDA i nazwa organizacji nie jest publikowana.
- 2
Wdrożenie wykorzystuje dedykowane adresy do identyfikacji wpłat stablecoin.
- 3
System utrzymuje registry powiązań adresów z kontekstem biznesowym.
- 4
Blockchain observer wykorzystuje checkpointing i możliwość replay.
- 5
Transfer jest walidowany pod kątem network, token contract, destination i amount.
- 6
Wykrycie transferu jest oddzielone od finalnego zaksięgowania w produkcie.
- 7
Product balance jest utrzymywany w niezależnym internal ledger.
- 8
Sweep i treasury są oddzielone od customer payment lifecycle.
- 9
Nieprawidłowe lub niejednoznaczne transfery trafiają do kontrolowanej obsługi wyjątków.
- 10
Nie publikujemy modelu custody, kluczy, adresów, wolumenów ani parametrów bezpieczeństwa.
Materiały wizualne
Diagramy przedstawiają potwierdzony zakres produktu i przepływy opisane w materiale. Nie są makietami ani deklaracją nieudokumentowanych wyników.
FAQ
Czy każdy klient musi mieć osobny wallet?
Nie zawsze. Dedykowany adres może być przypisany do użytkownika, konta, faktury lub payment intent — zależnie od modelu biznesowego, prywatności, kosztów i wybranego podejścia custody.
Dlaczego blockchain balance nie jest saldem użytkownika?
Saldo adresu mówi tylko, ile aktywów znajduje się on-chain. Nie mówi, do jakiego zobowiązania należał transfer, czy został zaakceptowany, czy jest finalny ani czy środki zostały już zaksięgowane w produkcie.
Jak system radzi sobie z awarią RPC lub indexera?
Observer przechowuje checkpointy i przetwarza bloki idempotentnie, dzięki czemu po przerwie może kontynuować od znanego miejsca lub odtworzyć wybrany zakres bez podwójnego zaksięgowania zdarzeń.
Czy sweep do treasury oznacza, że płatność jest dopiero wtedy zakończona?
Nie. Uznanie payment intent i ruch treasury to osobne workflow. Awaria sweepingu nie powinna cofać prawidłowo potwierdzonej płatności klienta.
Jak obsługiwane są złe tokeny i sieci?
Transfer jest klasyfikowany przez network, token contract, destination i amount. Zdarzenia niespełniające warunków payment intent nie są automatycznie księgowane jako prawidłowa płatność.
