Balans we gapjyklar: multi-wallet arhitekturasy

1) Näme üçin multi-wallet we haýsy maksatlar

Bir "balans = san" ýazgysy iGaming hakykatyny ýapmaýar. Aýratyn gapjyklar/kömekçi hasaplar gerek: hakyky pul (nagt), bonus serişdeleri, weýjer-howuz, frispinler, komp-nokatlar, käwagt - walýuta gapjyklary (EUR/USD/BRL).

Arhitektura maksatlary:

• Puluň takyklygy (double-entry, auditoriýa).
• Hasapdan çykarmak syýasaty (mysal üçin, ilki bonus/söwdagär, soň cash).
• Tizlik (p95 API ≤ 250-400 ms, hakyky wagtda nyrh/düzüliş).
• Howpsuzlyk we laýyklyk (KYC/AML, jogapkär oýnuň çäkleri, düzgünleşdirijiler).
• Masştab: iň ýokary → on müňlerçe amal/sek, milliardlarça posting/aý.

---

2) Maglumatlar modeli: "Ledger + Subwallets"

Iň az zatlar

Account: oýunçy/marka/bazar.

Tablisalaryň mysaly (ýönekeýleşdirilen)

sql
-- Double-entry üçin balans hasaplary (hyzmat hasaplaryny goşmak bilen)
accounts(id, owner_user_id, type, currency, status,...)

-- Geçiriş (goşa ýazgy, iş amalyna salgylanma)
ledger_entries(id, posting_id, debit_account_id, credit_account_id,        amount_minor, currency, category, operation_id, created_at)

-- Hold (ätiýaçlyk)
holds(id, account_id, amount_minor, currency, reason, expires_at, state,    operation_id, created_at)

- - Hasapdan çykarmak syýasaty (ileri tutulýan ugurlar)
spend_policies(id, market, wallet_priority jsonb, updated_at)

-- Kross-walýuta hümmeti fx_rates (ccy_from, ccy_to, rate, precision, valid_from)

Düzgün: Hakykat geçiriş journalurnalynda ýaşaýar ('ledger _ entries'). Häzirki balans - ýa agregat (materiallaşdyrylan snapshot), ýa-da žurnaldan hasaplanylýar (gymmat, ýöne ýeke-täk dogry).

---

3) Gapjyklaryň görnüşleri we olaryň özüni alyp barşy

---

4) Hasapdan çykarmak syýasaty we ileri tutulmagyň tertibi

Serişde çeşmesiniň algoritmini anyk resmileşdiriň: Mysal üçin:

1. Ilki WAGER-den ýazyň (eger Wager işjeň bolsa).

2. Soňra BONUS-dan entek gutarmanka.

3. Galyndy - CASH.

Mysal üçin:

1. Ilki bilen CASH (düzgünleşdiriji/salgyt).

2. Soňra WAGER-e terjime etmek arkaly BONUS (freebet).

Postings-de "syýasat çözgüdini" bir atribut hökmünde saklaň, şonuň üçin sapport we audit "näme üçin beýle ýazylandygyny" görer.

---

5) Pul we amallaryň durmuş sikli

Goýum

1. 'POST/wallet/deposit' → pending ýazgysyny (PSP kolback inbox) döredýäris.

2. PSP webhuk (goly HMAC, idempotentlik 'operation _ id') → credit CASH, category = 'DEPOSIT'.

3. Wakany 'wallet _ updated' diýip çap edýäris.

Nyrh

1. 'POST/bet/place' → çeşmäniň hasabynda hold (ätiýaçlyk) döredýäris (CASH/BONUS/WAGER).

2. Nyrh tassyklanylanda → transfer hold → debit çeşmesi, üpjün edijiniň hyzmat "hasaplaşyk" hasabynyň krediti.

3. Ýatyrylanda - release hold.

Settlement (netije)

Ýeňiş: üpjün edijiniň "hasaplaşyk" hasabynyň debit → credit CASH ýa-da WAGER → BONUS → CASH syýasaty boýunça.

Utulmak: üpjün edijiniň "sarp ediş" simleri bilen ýapýarys → oýunçy üçin karzsyz.

1. KYC/AML barlagy, jogapkär oýnuň çäkleri.

2. Çekiş üçin Hold.

3. PSP-iň üstünligi → soňky debit CASH → credit "töleg" hasaby.

4. PSP → release hold.

---

6) Idempotentlik we exactly-once "manysy boýunça"

Hemme ýerde 'operation _ id' (UUID/kämilleşdirilen ULID) özboluşly indeksli. Soňky amalyň statusy.

PSP/oýun üpjün edijisiniň webhuklary: 'event _ id + signature' üçin dedupe bilen Inbox tablisasy. Gaýtadan işlemek - idempotent worker (Outbox-pattern).

Idempotency-Key HTTP-de müşderi üçin; TTL saklamak ≥ 24-72 sagat.

---

7) Ätiýaçlyklar we holdlar (holds)

Hold - hasapdan çykarmak däl-de, elýeterli galyndylary "doňdurmak".

Düzgünler:

• Holdyň ömri: sekonds → minutes (jedel) ýa-da sagat (netije).
• Hold bölekleýin ýa-da doly tölenip bilner (partial settle).
• Expire - awtomatiki release we waka.
• Aragatnaşygyňyzy saklaň 'hold _ id' bet _ id/withdraw _ id '.

---

8) Walýutalar, FX we tegeleklemek

Pul mukdary - minor birliklerde (cents), görnüşi - bütinleý.

Bank tegelekleri (round half to even) ýa-da T&C boýunça.

FX: 'CASH (EUR) ' CASH (USD) 'gapjyklary bölmek has gowudyr. Konwersiýany aýratyn amal hökmünde amala aşyrmak:

• 'debit EUR, credit FX_EURUSD' we' debit FX_EURUSD, credit USD '- audit üçin aç-açan.
• Jedel ýüze çykan halatynda "ýetmek" awtomatiki usulda gadagan edilýär; ähli düzgünler - FX syýasatynda.

---

9) Jogapkär oýun we çäkler

Deposit/Bet/Loss/Session limitleri (gün/hepde/aý), "cooling-off", self-exclusion.

hold/debit-den öň pre-check hökmünde amala aşyrylýar.

Ret ediş ýazgylary - aýratyn audit-journalurnalda, sapport we düzgünleşdiriji üçin elýeterlidir.

---

10) Gapjygyň töweregindäki antifrod signallary

Enjamlar klasterleri/ASN, ýygy-ýygydan az mukdarda goýumlar → uly netijeler, ýuwulýan patternler.

BIN/ýurt/enjam boýunça 'deposit/withdraw' -a Velocity-çäkleri.

Alýanlar üçin blok-listler (gapjyklar/IBAN), "gatylyklaryň" sanawy.

Gapjyk wakalary → feature store skoring (giriş/goýum/stawka).

---

11) Yzygiderlilik we öndürijilik

Hakykat vs kesh

Hakykat - ledger. API üçin "balans almak" - materiallaşdyrylan snapshot ('user _ id + wallet _ type → balance_minor, version') saklaň.

Ýazmak: geleşik DB → maýyp kesmek.

"Agyr" flowlarda (göni ýaýlymda) short-TTL 1-5 + çykarmazdan/uly nyrhdan öň hakykaty hökmany barlamak ýerliklidir.

Gaýa

"User _ id" boýunça şardlamak (modul/reýting), CASH vs BONUS astynda aýry-aýry şard-howuzlar.

Gyzgyn açarlar (VIP/botlar) - request coalescing by 'user _ id'.

Asinxron agregasiýalar (fonda 'posting' → "snapshot-updater" toparyny düzüň).

---

12) API-şertnamalar (psevdo)

Balans

http
GET /v1/wallets? types=CASH,BONUS
→ 200 {"wallets":[
{"type":"CASH","currency":"EUR","available":12050,"hold":500,"version":1942},  {"type":"BONUS","currency":"EUR","available":3000,"wager_req":15000}
]}

Stawka (hold bilen)

http
POST /v1/bets/place
{"bet_id":"b_123","amount":500,"currency":"EUR","source_policy":"casino_default", "idempotency_key":"ik_abc"}
→ 201 {"status":"HELD","hold_id":"h_789","expires_in":30}

Settlement

http
POST /v1/bets/settle
{"bet_id":"b_123","result":"WIN","payout":1250}
→ 200 {"status":"SETTLED","cash_delta":+1250}

http
POST /v1/withdrawals
{"withdraw_id":"w_456","amount":10000,"currency":"EUR","method":"sepa", "idempotency_key":"ik_def"}
→ 202 {"state":"PENDING","next_check_sec":2,"status_url":"/v1/withdrawals/w_456"}

---

13) Simleriň mysallary (double-entry)

Goýum €100 (PSP fee €1, kommis. hasap - aýratyn)

Debit: PSP_Settlements(EUR)   10000
Credit: User. CASH(EUR)         10000

Debit: User. CASH (EUR) 100 (fee göçürýäris)
Credit: PSP_Fees(EUR)          100

BONUS-dan €5 (WAGER-e terjime)

Debit: User. BONUS(EUR)       500
Credit: User. WAGER (EUR) 500 ("Wager" -e göçmek)
Debit: User. WAGER(EUR)       500
Credit: Provider. Settlement (EUR) 500 (stawka hasapdan çykaryldy)

Ýeňiş €12. 5 → CASH

Debit: Provider. Settlement(EUR)  1250
Credit: User. CASH(EUR)         1250

Hold hasapdan çykarmak (HOLD hyzmat hasaby arkaly satmak)

Debit: User. CASH(EUR)       500
Credit: User. HOLD (EUR) 500 (hold tarapyndan döredildi)
-- settle
Debit: User. HOLD(EUR)       500
Credit: Provider. Settlement(EUR)   500
-- ýatyrylanda
Debit: User. HOLD(EUR)       500
Credit: User. CASH(EUR)         500

---

14) Audit, üýtgemezlik we laýyklyk

WORM/immutability (obýekt ammary/WAL arhiwi).

Giriş meta-ýazgylary: kim okady/üýtgetdi, kim el bilen düzedişler etdi (diňe esasly "adjustment-posting" arkaly).

GDPR/düzgünleşdirijiler: amallary 5-10 ýyl saklamak (ýurisdiksiýa boýunça), oýunçy üçin hasaplamalaryň aç-açanlygy (hasapdan çykarmalaryň/söwdanyň taryhy).

---

15) Näsazlyga çydamlylyk we DR

Multi-AZ hökmanydyr; Gapjyk üçin DR sebiti: zonada sync-replikasiýa, sebite async; PITR açyldy.

Promote standby - diňe çek sanawy boýunça el bilen (split-brain-i aýyrmak).

Dikeldiş hepdede barlanylýar (test-restore), gözegçilik hasabatlary boýunça mukdar barlagy.

---

16) Gapjygyň syn edilmegi

SLI: `deposit_success_ratio`, `withdraw_success_ratio`, `bet_hold_latency_p95`, `settlement_latency_p95`.

Тех: `ledger_postings_rate`, `db_connections_saturation`, `queue_lag_seconds`, `hold_expired_rate`.

Alertler: PSP-iň bazara düşmegi, 'hold _ expired _ rate', oýun üpjün edijisiniň bölünişigi (tassyklama ýok> N min).

---

17) Synag we hil gözegçiligi

PSP/oýun üpjün edijileri bilen şertnama synaglary (webhuklar/gollar).

Property-based pul synaglary: her Posting-de debetleriň jemi = = karzlaryň jemi.

Fuzz/chaos: PSP/üpjün edijiniň gijikdirilmegi, webhuklaryň gaýtalanmagy, tor fappleri.

Ýükleýiş: burst stawkalary (60-120 s), soaks (4-8 s), gözegçilik 'queue _ lag' we p99.

---

18) Önümçilik taýýarlygynyň çek-sanawy

• Goşa ýazgy ledger, Posting arkaly ähli amallar 'operation _ id'.
• Anyk spend-policies we ileri tutulýan tertip (posting bilen bilelikde).
• TTL/partial settle/expiry, bet/withdraw bilen baglanyşyk.
• Inbox/Outbox, HMAC-webhuks, ähli serhetlerde idempotentlik.
• Aýry-aýry NAGT/BONUS/WAGER/FS/POINTS gapjyklary; walýutalar boýunça bölünişik.
• FX we kiçi birliklerde tegelek; konwersiýa - aýratyn amal.
• hold/debit çenli jogapkär oýun çäkleri; şowsuzlyklaryň barlagy.
• Okamak üçin nagt pul (gysga TTL) + möhüm hereketlerden öň hakykaty hökmany barlamak.
• PITR/bellikler/DR skriptleri; el bilen promote, yzygiderli DR-maşklar.
• Daşbordlar/alertler SLI + tehniki; WORM ýazgylary we giriş meta-ýazgylary.
• Ýüklemek/bulam-bujarlyk synaglary; PSP/üpjün edijiler bilen reconciliation hasabatlary.

---

Jemleme

Multi-wallet arhitekturasy "köp sanly balans" däl-de, iki gezek ýazylan, çykdajy syýasatlary, ätiýaçlyk we audit we oýunçylar üçin aç-açan yzly maliýe ulgamy. Hakykaty magazineurnalda saklaň, gapjyklary we walýutalary paýlaşyň, gapjyklary we walýutalary bölüň, reconciliation we DR. şeýlelik bilen gapjyk UX üçin çalt, pul üçin takyk we iň ýokary ýükler we kadalaşdyryjy barlaglar üçin durnukly bolar.