-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdocs.html
More file actions
637 lines (524 loc) · 48.6 KB
/
Copy pathdocs.html
File metadata and controls
637 lines (524 loc) · 48.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Octo Rewards — Документация интеграции</title>
<meta name="description" content="Подробная документация по интеграции Octo Rewards Gateway: CBDC, токены, маркетплейс данных, интеграции для частных, бизнес и гос.органов" />
<style>
/* Стиль инфографики — AR/holographic feel */
:root{ --bg:#061028; --glass: rgba(255,255,255,0.03); --accent1:#7dc8ff; --accent2:#c878ff; --muted:rgba(255,255,255,0.65); --card:#0f1a2b; }
html,body{height:100%;margin:0;font-family:Inter,Roboto,Arial,sans-serif;background-color:#031026;color:#e6f6ff}
header{position:sticky;top:0;background:linear-gradient(180deg,rgba(255,255,255,0.02),transparent);backdrop-filter:blur(6px);padding:18px 28px;display:flex;align-items:center;gap:18px;border-bottom:1px solid rgba(255,255,255,0.03);z-index:10}
header img{height:36px}
header h1{font-size:18px;margin:0}
nav.toc{margin-left:auto;display:flex;gap:10px}
nav.toc a{color:var(--muted);text-decoration:none;padding:8px 10px;border-radius:8px;font-size:13px}
.container{max-width:1100px;margin:28px auto;padding:20px}
.grid{display:grid;grid-template-columns:360px 1fr;gap:20px}
/* левое меню инфографики */
.sidebar{background:linear-gradient(180deg,rgba(255,255,255,0.02),transparent);border:1px solid rgba(255,255,255,0.03);padding:14px;border-radius:12px}
.sidebar h3{margin:6px 0 12px 0}
.pill{display:inline-block;padding:6px 10px;border-radius:999px;background:rgba(255,255,255,0.02);font-size:12px}
.kpi{display:flex;flex-direction:column;gap:8px}
.kpi .item{background:var(--card);padding:10px;border-radius:10px;border:1px solid rgba(255,255,255,0.02)}
/* основной контент */
.doc{background:linear-gradient(180deg, rgba(255,255,255,0.01), transparent);padding:18px;border-radius:12px;border:1px solid rgba(255,255,255,0.03)}
h2{margin-top:8px;color:var(--accent1)}
h3{color:var(--accent2)}
p.lead{color:var(--muted);font-size:14px}
section{margin-bottom:20px}
/* кодовые блоки */
pre.code{background:#051227;padding:12px;border-radius:10px;border:1px solid rgba(255,255,255,0.03);overflow:auto;font-size:13px}
code.inline{background:rgba(255,255,255,0.02);padding:2px 6px;border-radius:6px}
/* карточки архитектуры */
.row-cards{display:flex;gap:12px;flex-wrap:wrap;margin-top:12px}
.card{flex:1;min-width:220px;background:linear-gradient(180deg,rgba(255,255,255,0.02),transparent);border-radius:10px;padding:12px;border:1px solid rgba(255,255,255,0.03)}
table{width:100%;border-collapse:collapse;margin-top:8px}
table th, table td{padding:8px;border-bottom:1px dashed rgba(255,255,255,0.03);text-align:left;font-size:13px}
.foot{font-size:12px;color:var(--muted)}
/* responsive */
@media (max-width:1000px){ .grid{grid-template-columns:1fr} .sidebar{order:2} }
</style>
</head>
<body>
<header>
<a href="https://cbdcapi.github.io/" style=" text-decoration:none;color:unset;display:contents;" target="blank">
<img src="https://blockchainaccreditive.github.io/css/iokwa.svg" alt="logo" />
<h1>Octo Rewards — Документация интеграции</h1>
</a>
<nav class="toc">
<a href="#overview">Обзор</a>
<a href="#architecture">Архитектура</a>
<a href="#api">API & Форматы</a>
<a href="#examples">Примеры</a>
<a href="#security">Безопасность</a>
</nav>
</header>
<div class="container">
<div class="grid">
<aside class="sidebar">
<h3>Краткая навигация</h3>
<div class="kpi">
<div class="item"><strong>Цели</strong><div class="foot">Компенсация прогресса игроков, турниров, гибкая интеграция CBDC / токенов / маркетплейса данных</div></div>
<div class="item"><strong>Поддержка</strong><div class="foot">Web, Mobile, Unity, Unreal, Backend (Node/Java/Go/Python)</div></div>
<div class="item"><strong>Сценарии</strong><div class="foot">Частный / Бизнес / Государство — разные правила KYC/SLA/Отчётности</div></div>
</div>
<h3 style="margin-top:12px">Контрольные точки интеграции</h3>
<ol style="padding-left:16px;color:var(--muted)">
<li>Определить модель монетизации</li>
<li>Выбрать канал выплат <!--(CBDC / on-chain token / data marketplace)--></li>
<li>Зарегистрировать систему в sandbox (EMTECH / Цифровой рубль)</li>
<li>Настроить KYC / AML / Audit</li>
<li>Запуск пилота → интеграционное тестирование → выпуск</li>
</ol>
<h3 style="margin-top:12px">Контакты</h3>
<div class="foot">Техническая поддержка: dev@holographic.rewards</div>
</aside>
<main class="doc">
<!-- OVERVIEW -->
<section id="overview">
<h2>Обзор</h2>
<p class="lead">Octo Rewards — модульный шлюз вознаграждений для игр и приложений.<br>
Позволяет начислять игрокам материальные вознаграждения за прогресс и время игры через различные каналы:<br> CBDC (e‑Cedi, цифровой рубль), ончейн токены (ERC‑20 / EVM), и продажу анонимных наборов данных (маркетплейс).</p>
<h3>Ключевые понятия</h3>
<ul>
<li><strong>Gateway</strong> — центральный компонент: принимает события от клиента, рассчитывает вознаграждение и отправляет команду на settlement adapter.</li>
<li><strong>Settlement Adapter</strong> — адаптер к конкретной системе выплат (CBDC API, blockchain RPC, marketplace API).</li>
<li><strong>Event</strong> — структурированное сообщение о прогрессе игрока (time_played, milestone, task_completed).</li>
<li><strong>Rules Engine</strong> — конфигурируемая логика расчёта выплат (pay per hour, milestone rewards, diminishing returns, governance multipliers).</li>
</ul>
<h3>Поддерживаемые интеграции</h3>
<div class="row-cards">
<div class="card"><strong>CBDC</strong><div class="foot">EMTECH e‑Cedi, цифровой рубль — через sandbox API и production adapters.</div></div>
<div class="card"><strong>On‑chain</strong><div class="foot">Mint & transfer ERC‑20 / native token; подписанные транзакции через MetaMask / WalletConnect / Server signer.</div></div>
<div class="card"><strong>Data marketplace</strong><div class="foot">Сбор и продажа анонимных телеметрических данных — Filecoin/IPFS для хранения + маркеты для продажи.</div></div>
</div>
</section>
<!-- ARCHITECTURE -->
<section id="architecture">
<h2>Архитектура</h2>
<p class="lead">Единая архитектура позволяет подключать Gateway как API в любую игру или приложение. Стек типично включает клиентские SDK, backend-интегратор, Rules Engine и множество Settlement Adapter'ов.</p>
<h3>Компоненты</h3>
<table>
<tr><th>Компонент</th><th>Задачи</th></tr>
<tr><td>Client SDK</td><td>Формирование событий, подпись (по требованию), queue и ретрай</td></tr>
<tr><td>Gateway API</td><td>Приём событий, валидация, маршрутизация в Rules Engine</td></tr>
<tr><td>Rules Engine</td><td>Политики выплат, лимиты, KYC/AML checks</td></tr>
<tr><td>Settlement Adapters</td><td>Интеграция с CBDC, blockchain, платёжными провайдерами</td></tr>
<tr><td>Accounting</td><td>Рассчёт налогов, отчётность, reconciliation</td></tr>
</table>
<h3>Простой поток событий (sequence)</h3>
<ol style="color:var(--muted)">
<li>Клиент отправляет Event → Gateway (HTTPS POST или websocket)</li>
<li>Gateway валидирует событие, проверяет подпись</li>
<li>Rules Engine рассчитывает сумму и проверяет лимиты/KYC</li>
<li>Создаётся транзакция в Settlement Adapter</li>
<li>Settlement Adapter подтверждает выполнение — Accounting обновляет статус</li>
</ol>
<h3>JSON example: Event schema</h3>
<pre class="code">{
"event_id":"uuid-v4",
"game_id":"octocore.v1",
"player_id":"did:player:abcd1234",
"event_type":"time_played|milestone|task",
"progress_metric":{ "time_played_seconds":3600, "level":12, "score":12345 },
"timestamp":"2025-08-10T12:34:56Z",
"signature":"base64-or-did-auth-proof"
}</pre>
<p class="foot">Подпись — опциональна, но обязательна для high-value выплат; используется сервисный ключ или <a href="https://tangem.com/ru/blog/post/decentralized-identifiers-dids/" style="text-decoration:none;color:green;" target="blank">DID-подпись клиента.</a></p>
</section>
<!-- API -->
<section id="api">
<h2>API & Форматы</h2>
<h3>1) Приём событий — POST /api/v1/events</h3>
<pre class="code">POST /api/v1/events
Content-Type: application/json
Authorization: Bearer <gateway-api-key>
{ ... event as above ... }
Response 202 Accepted
{ "ingest_id":"uuid", "status":"queued" }
</pre>
<h3>2) Webhook callback (async result)</h3>
<pre class="code">POST /webhooks/rewards
Headers: X-Signature: hmac_sha256(<secret>, body)
{ "ingest_id":"uuid","settlement_status":"settled","tx_ref":"ecedi-12345","amount":0.5 }
</pre>
<h3>3) Управление правилами (Admin)</h3>
<pre class="code">GET /admin/rules
POST /admin/rules { name: 'payPerHour', value: 0.1 }
</pre>
<h3>Примеры клиентской отправки (JavaScript)</h3>
<pre class="code">// Простой пример отправки события через fetch
var evt = {
event_id: 'evt_' + Math.random().toString(36).slice(2),
game_id: 'octocore.v1',
player_id: 'did:player:abc',
event_type: 'time_played',
progress_metric: { time_played_seconds: 3600 },
timestamp: new Date().toISOString()
};
fetch('https://gateway.example.com/api/v1/events', {
method: 'POST', headers: { 'Content-Type':'application/json', 'Authorization':'Bearer YOUR_KEY' },
body: JSON.stringify(evt)
}).then(function(r){ return r.json(); }).then(console.log).catch(console.error);
</pre>
<h3>Server-side: Webhook verification (Node/Express)</h3>
<pre class="code">// Node.js express example
var crypto = require('crypto');
app.post('/webhooks/rewards', function(req,res){
var secret = process.env.WEBHOOK_SECRET;
var sig = req.headers['x-signature'];
var computed = crypto.createHmac('sha256', secret).update(JSON.stringify(req.body)).digest('hex');
if(!sig || sig !== computed){ res.status(401).end('invalid signature'); return; }
// обработать результат
res.status(200).send({ok:true});
});
</pre>
<h3>Idempotency и повторная обработка</h3>
<p class="foot">Каждое событие должно иметь уникальный <code class="inline">event_id</code>. Gateway гарантирует at-least-once delivery для Adapter'ов; Settlement Adapter должен быть идемпотентным (используйте <code class="inline">ingest_id</code> или <code class="inline">event_id</code> в качестве idempotency key).</p>
</section>
<!-- Examples per platform -->
<section id="examples">
<h2>Примеры интеграции по платформам</h2>
<h3>Веб (Browser)</h3>
<p class="foot">Подключите клиентский SDK/просто используйте fetch. Для on-chain выплат интегрируйте MetaMask / WalletConnect.</p>
<pre class="code">// Пример отправки события и запроса на выплату через сервера
// Клиент -> Gateway: POST /api/v1/events
// Gateway -> Rules Engine -> Settlement Adapter -> (EMTECH/Blockchain)
</pre>
<h3>Mobile: iOS / Android / React Native</h3>
<p class="foot">Используйте native HTTP client; для on-chain интеграции используйте WalletConnect 2.0 для мобильных кошельков.</p>
<pre class="code">// Android (Kotlin) — отправка события (пример)
/*
val evtJson = ...
val client = OkHttpClient()
val req = Request.Builder().url("https://gateway.example.com/api/v1/events")
.header("Authorization", "Bearer YOUR_KEY")
.post(RequestBody.create(MediaType.parse("application/json"), evtJson))
.build()
client.newCall(req).enqueue(...)
*/
</pre>
<h3>Unity (C#)</h3>
<p class="foot">В Unity используйте UnityWebRequest для отправки событий и подписи через native plugin, если нужен secure enclave.</p>
<pre class="code">// Unity C# — отправка простого события
/*
using UnityEngine.Networking;
var evt = JsonUtility.ToJson(yourEvent);
UnityWebRequest.Post("https://gateway.example.com/api/v1/events", evt);
*/
</pre>
<h3>Game engines — общие рекомендации</h3>
<ul>
<li>Клиент отправляет только события; бизнес-логика расчёта выплат выполняется на сервере.</li>
<li>Минимизируйте привязку секретов к клиенту — используйте transient tokens и server-side signing.</li>
<li>Поддерживайте оффлайн-очередь и ретрай — сетевые прерывания в играх обычны.</li>
</ul>
<h3>Backend: Node / Python / Java / Go</h3>
<p class="foot">При реализации Settlement Adapter'ов используйте проверенные SDK и HTTP clients; следите за retry, circuit breaker и idempotency.</p>
<h3>On-chain example (ethers.js) — mint & transfer</h3>
<pre class="code">// Node.js (ethers.js)
const { ethers } = require('ethers');
const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL);
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider);
const tokenAbi = [ 'function mint(address to, uint256 amount) external' ];
const token = new ethers.Contract(process.env.TOKEN_ADDR, tokenAbi, wallet);
await token.mint(playerAddress, ethers.utils.parseUnits('1.0', 18));
</pre>
<h3>Smart contract (Solidity) — простой mintable ERC20</h3>
<pre class="code">// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
contract GameRewardToken is ERC20, Ownable {
constructor() ERC20("GameReward", "GRD") {}
function mint(address to, uint256 amount) external onlyOwner { _mint(to, amount); }
}
</pre>
</section>
<!-- Integration types -->
<section id="integration_types">
<h2>Интеграция: Частная, Бизнес, Государство</h2>
<h3>Частные интеграции (инди-разработчики и малые студии)</h3>
<ul>
<li>Используйте gateway sandbox key, lightweight KYC (если выплаты < threshold).</li>
<li>Примеры: внутриигровые микровыплаты для мобильных игр, платные подписки с выплатой за время.</li>
<li>Требования по audit: базовый логинг, экспорт журнала транзакций.</li>
</ul>
<h3>Бизнес (коммерческие студии и платформы)</h3>
<ul>
<li>Интеграция с бухгалтерией и налоговыми отчётами, SLA, SLA‑monitoring для выплат, KYC/AML партнёрство.</li>
<li>Обычно нужен серверный агрегатор (middleware) — чтобы скрывать секреты и управлять очередями выплат.</li>
</ul>
<h3>Гос. органы / публичные проекты</h3>
<ul>
<li>Строгое соответствие нормативам, требование audit trail, подробный регламент доступа и межведомственное взаимодействие.</li>
<li>Интеграция с CBDC API (как EMTECH) через официальный sandbox и подписанные API‑ключи, регулярные проверки безопасности.</li>
</ul>
<h3>Таблица сравнения требований</h3>
<table>
<tr><th>Аспект</th><th>Частные</th><th>Бизнес</th><th>Гос</th></tr>
<tr><td>KYC</td><td>опционально</td><td>обязательно выше threshold</td><td>обязательно, строгий</td></tr>
<tr><td>SLA</td><td>низкий</td><td>высокий</td><td>очень высокий / регламентированный</td></tr>
<tr><td>Отчётность</td><td>минимальная</td><td>фин. отчётность + налог</td><td>полные логи, аудит</td></tr>
</table>
</section>
<!-- Security -->
<section id="security">
<h2>Безопасность, соответствие и операции</h2>
<h3>1. Аутентификация и авторизация</h3>
<ul>
<li>API Keys: строгие права (scopes) — разделяйте write/read/admin.</li>
<li>Webhook secret: HMAC signature для проверки источника.</li>
<li>Для on-chain: используйте безопасное хранение приватных ключей (HSM / KMS).</li>
</ul>
<h3>2. Подписи и доказательства</h3>
<p class="foot">Для high-value транзакций требуется cryptographic proof: DID‑подпись, JWT signed by client, или service-side signed request.</p>
<h3>3. KYC/AML</h3>
<p class="foot">Интеграция со сторонними провайдерами KYC (Jumio, Onfido и т.п.) по необходимости. Threshold для KYC настраивается в Rules Engine.</p>
<h3>4. Anti‑fraud</h3>
<ul>
<li>Rate limits и anomaly detection (странные паттерны сессий).</li>
<li>Детектирование мультиаккаунтов и временных паттернов (анти-bot).</li>
<li>Автоматические блокировки по правилам.</li>
</ul>
<h3>5. Compliance & Logging</h3>
<ul>
<li>Все транзакции логировать: event_id, ingest_id, settlement_id, timestamps, responsible_actor.</li>
<li>Хранение audit trail минимум 5 лет — зависит от юрисдикции.</li>
</ul>
</section>
<!-- Testing and deployment -->
<section id="testing">
<h2>Тестирование и деплой</h2>
<h3>Sandbox режим</h3>
<p class="foot">Всегда начинайте с sandbox адаптеров (EMTECH sandbox, testnet для блокчейнов). В sandbox можно тестировать без реальных сущностей.</p>
<h3>Набор тестов</h3>
<ul>
<li>Unit tests: Rules Engine расчёты (payPerHour, milestone)</li>
<li>Integration tests: Gateway → Adapter (mock сервера)</li>
<li>End-to-end: Клиент → Gateway → Settlement → Webhook</li>
</ul>
<h3>Пример теста (Node + Mocha + Supertest)</h3>
<pre class="code">var request = require('supertest');
var app = require('../app');
describe('POST /api/v1/events', function(){
it('should accept event', function(done){
request(app).post('/api/v1/events')
.send({ event_id:'test1', game_id:'g', player_id:'p1', event_type:'time_played', progress_metric:{time_played_seconds:3600} })
.expect(202, done);
});
});
</pre>
<h3>Мониторинг</h3>
<ul>
<li>Метрики: latency (gateway/adapters), success_rate, payout_volume</li>
<li>Алерты: повышенная ошибка адаптера, queue backlog, необычный spike в выплатах</li>
</ul>
</section>
<!-- Economics -->
<section id="economics">
<h2>Экономика и модели монетизации</h2>
<p class="lead">Ниже — типовые модели монетизации и примеры расчёта.</p>
<h3>Модели</h3>
<ol style="color:var(--muted)">
<li><strong>Pay‑per‑time</strong> — выплата за проведённое время (например 0.10 USD за 60 минут)</li>
<li><strong>Milestone</strong> — фиксированная выплата за достижения (уровень, миссия)</li>
<li><strong>Revenue share / Data sale</strong> — доход от продажи анонимных данных распределяется между игроками</li>
</ol>
<h3>Пример распределения (Data marketplace)</h3>
<p class="foot">Если набор данных продан за 100 USD и договорено, что игроки получают 60%:</p>
<pre class="code">revenue = 100
players_pool = 0.6 * revenue = 60
player_share = (player_contrib / total_contrib) * players_pool
</pre>
</section>
<section id="architecture">
<h2>Архитектура (напоминание)</h2>
<p class="lead">Единая архитектура: Client SDK → Gateway → Rules Engine → Settlement Adapters → Accounting / Webhooks. Мощный пункт — интеграция провайдеров идентификации и подписи (MAX, Госуслуги/ЕСИА, удостоверяющие центры) для надёжного KYC/Legal signing.</p>
<h3>Поток событий</h3>
<ol style="color:var(--muted)">
<li>Client отправляет Event (POST / websocket) — опционально подписывает события DID-подписью</li>
<li>Gateway валидирует подпись + payload
<li>Rules Engine вычисляет reward, проверяет лимиты и уровень KYC</li>
<li>Settlement Adapter инициирует выплату (CBDC API / on-chain tx / marketplace sale)</li>
<li>Accounting логирует и отправляет webhook результат</li>
</ol>
</section>
<section id="max">
<h2>Интеграция с мессенджером MAX — возможности и сценарии</h2>
<p class="lead">MAX можно использовать как идентификационный и подписиный шлюз: он облегчает KYC/AML, предоставляет DID-подписи и поддерживает цифровые сервисные ключи (ЭП/ЭЦП). Ниже — практические сценарии и архитектурные рекомендации.</p>
<h3>Почему MAX помогает</h3>
<ul>
<li><strong>Готовая идентификация</strong>: MAX часто интегрирован с ЕСИА/Госуслугами и партнёрскими удостоверяющими центрами — это позволяет получать подтверждённые данные о личности.</li>
<li><strong>DID-подписи</strong>: MAX может выпускать DID-учётные записи, которые используются для подписания сообщений без раскрытия всех личных данных.</li>
<li><strong>ЭЦП/ЭП</strong>: сервис позволяет производить юридически значимые подписи (электронная подпись) или подписывать транзакции цифровым сервисным ключом организации.</li>
<li><strong>Удобство UX</strong>: встроенная авторизация через мессенджер снижает барьер входа для игроков.</li>
</ul>
<h3>Типовые сценарии с MAX</h3>
<h4>1) Быстрая регистрация и KYC</h4>
<p class="foot">Игрок кликает «Войти через MAX». MAX возвращает утверждённый профиль (имя, дата рождения, подтверждённый email/телефон), а также статус верификации ESIA (при наличии). Gateway помечает пользователя как KYC-verified и разрешает higher-value payouts.</p>
<h4>2) DID-подпись событий</h4>
<p class="foot">Клиент получает DID-ключ в MAX и подписывает важные события (например, запрос на вывод средств). Gateway проверяет DID-подпись и обрабатывает запрос как авторизованный.</p>
<h4>3) Подпись цифровым сервисным ключом (ЭЦП/ЭП)</h4>
<p class="foot">Организация, интегрированная с MAX и удостоверяющим центром, может подписывать массовые batch‑выплаты юридически значимой ЭЦП. Это особенно важно в B2G сценариях и при передаче отчётности.</p>
<h3>Архитектурный пример: MAX как Identity & Signing Gateway</h3>
<pre class="code">Client (game) --auth--> MAX (OAuth/ESIA) --assertion--> Gateway
Client signs event with DID (MAX) --> Gateway validates DID
Gateway requests settlement --> Adapter подписывает batch с ЭЦП сервиса (через MAX/UC)</pre>
<h3>Ограничения и нюансы</h3>
<ul>
<li>Наличие обязательств по хранению персональных данных: даже при использовании MAX вы должны соблюдать local privacy laws.</li>
<li>Не все пользователи хотят привязывать мессенджер к игровому аккаунту — предложите альтернативы (email, social logins).</li>
<li>Юридическая значимость ЭЦП требует согласования с удостоверяющим центром и регулятором.</li>
</ul>
<h3>Резюме по MAX</h3>
<p class="foot">MAX существенно упрощает KYC/AML и подписи, особенно в российской экосистеме. Рекомендуется как primary identity provider для операций, где требуется подтверждённая юр. сила подписи.</p>
</section>
<section id="api">
<h2>API & Форматы (коротко)</h2>
<p class="lead">Основные endpoint'ы: /api/v1/events (ingest), /admin/rules, webhook callbacks. См. отдельный файл с OpenAPI для полного контракта.</p>
</section>
<section id="glossary">
<h2>Глоссарий — термины и определения</h2>
<h3>KYC (Know Your Customer)</h3>
<p class="foot">Процедуры верификации личности клиента: сбор документов (паспорт/ID), проверка через сторонние провайдеры (Jumio, Onfido) или государственные сервисы (ЕСИА/Госуслуги). Цель — убедиться, что пользователь — реальное лицо и оценить риск.</p>
<h3>AML (Anti-Money Laundering)</h3>
<p class="foot">Комплекс мер по противодействию отмыванию денег и финансированию терроризма: мониторинг транзакций, отчётность в FIU, тревожные флаги и блокировки.</p>
<h3>DID (Decentralized Identifier) <a href="https://tangem.com/ru/blog/post/decentralized-identifiers-dids/" style="text-decoration:none;color:white;" target="blank">(ссылка)</a></h3>
<p class="foot">Децентрализованный идентификатор — схема идентификации, где субъект имеет публичный DID и ассоциированные ключи. DID-подпись позволяет подтверждать происхождение данных без передачи всех персональных атрибутов.</p>
<h3>ЭЦП / ЭП (электронная цифровая подпись / электронная подпись)</h3>
<p class="foot">Юридически значимая подпись, подтверждаемая удостоверяющим центром (UC). В РФ часто используется термин ЭЦП. Используется для подписания юридически значимых документов и batch-платежей.</p>
<h3>Антифрод (Anti-Fraud)</h3>
<p class="foot">Система обнаружения мошенничества: правила, эвристики, ML-модели, поведенческая аналитика. Включает детекцию мультиаккаунтов, аномалий в метриках сессий и подозрительных паттернов выплат.</p>
<h3>HSM (Hardware Security Module)</h3>
<p class="foot">Аппаратный модуль безопасности для хранения приватных ключей. Рекомендуется для production custody ключей (как on-chain, так и для подписей ЭЦП).</p>
<h3>Multisig / Multi‑party signing</h3>
<p class="foot">Механизм, когда несколько ключей/партий должны подписать транзакцию; снижает риск одностороннего слива средств.</p>
<h3>Idempotency key</h3>
<p class="foot">Уникальный ключ для повторных вызовов API, чтобы предотвратить дублирование действий (например, двойные выплаты при retry).</p>
<h3>Nonce / Sequence</h3>
<p class="foot">Числовой счётчик, предотвращающий повторное воспроизведение транзакций в блокчейне или API.</p>
<h3>Settlement Adapter</h3>
<p class="foot">Компонент, реализующий интеграцию с конкретной системой выплат: CBDC API, blockchain RPC, PSP, marketplace.</p>
<h3>ESIA / Госуслуги</h3>
<p class="foot">Единая система идентификации и аутентификации в России. Интеграция с ESIA позволяет получать подтверждённые атрибуты личности у пользователей РФ.</p>
<h3>FIU (Financial Intelligence Unit)</h3>
<p class="foot">Национальный орган, который получает сообщения о подозрительных операциях и анализирует финансовые потоки (в РФ — Росфинмониторинг).</p>
<h3>Filecoin / IPFS</h3>
<p class="foot">Децентрализованные хранилища для больших наборов данных. Используются для безопасного хранения анонимизированных телеметрических наборов, которые затем продаются через marketplace.</p>
<h3>Sandbox</h3>
<p class="foot">Тестовая среда (EMTECH sandbox, CBDC тестовые конторы, blockchain testnets) для безопасной проверки интеграции без реальных средств.</p>
<h3>UBO (Ultimate Beneficial Owner)</h3>
<p class="foot">Конечный бенефициар компании — важно при KYC для юридических лиц.</p>
<h3>Webhook</h3>
<p class="foot">Callback URL, на который Gateway отправляет асинхронные уведомления о результатах settlement — подписываются HMAC для верификации.</p>
</section>
<section id="stake">
<h2>Что такое «стейк» игрока в нашем контексте</h2>
<p class="lead">В документации под <strong>стейком игрока</strong> мы понимаем сумму (денежную или в токенах), которую игрок блокирует в системе как гарантию поведения, квалифицирующее его на выплаты, привилегии или участие в governance. Стейк — это инструмент экономической и поведенческой дисциплины: он служит депозитом, репутационным сигналом и фильтром против злоупотреблений.</p>
<h3>Основные роли и цели стейка</h3>
<ul>
<li><strong>Валидация доступа к выплатам:</strong> минимальный стейк может быть предикатом, позволяющим игроку выводить реальные средства или участвовать в high-value выплатах.</li>
<li><strong>Антифрод / Anti‑Sybil:</strong> стейк повышает стоимость массового создания фейковых аккаунтов (farm), так как для каждого аккаунта требуется капитал.</li>
<li><strong>Сигнал репутации:</strong> размер и возраст стейка используются в правилах начисления (чем выше стейк — тем больше доверие / бонус).</li>
<li><strong>Экономический коллатераль:</strong> стейк может блокироваться для покрытия штрафов, чарджбэков или компенсаций в случае нарушения правил.</li>
<li><strong>Governance и участие:</strong> стейк может давать голос в управлении параметрами Rules Engine (например, голосование за изменение payPerHour).</li>
</ul>
<h3>Механики стейкинга — как это реализуется</h3>
<ul>
<li><strong>Типы стейка:</strong> <em>on‑chain</em> (ERC‑20 / native token locked in smart contract) или <em>custodial/off‑chain</em> (средства хранятся у оператора и блокируются в учётной записи).</li>
<li><strong>Lock / Unlock:</strong> при депозите стейк переводится в статус <code class="inline">locked</code> на заданный период. После окончания периода доступен <code class="inline">withdraw</code> с ожиданием (unbonding).</li>
<li><strong>Slashing / Penalties:</strong> при нарушениях часть или весь стейк может быть изъят (slashed) согласно правилам (fraud detection, chargeback).</li>
<li><strong>Stake as collateral:</strong> стейк может быть резервом для immediate payouts — например, если у оператора временно нет возможности провести выплату в CBDC, он использует часть стейка как гарантию возврата.</li>
</ul>
<h3>On‑chain vs Custodial — плюсы и минусы</h3>
<table>
<tr><th>Критерий</th><th>On‑chain</th><th>Custodial (off‑chain)</th></tr>
<tr><td>Прозрачность</td><td>Максимальная — все транзакции в блокчейне</td><td>Зависит от оператора, требует доверия</td></tr>
<tr><td>Контроль пользователя</td><td>Пользователь контролирует ключи</td><td>Оператор держит средства, проще UX</td></tr>
<tr><td>Регуляторика</td><td>Сложнее (crypto rules)</td><td>Проще подстраиваться под локальные правила и CBDC</td></tr>
<tr><td>Стоимость (gas)</td><td>Да — операции стоят газа</td><td>Нет прямых газ‑трат</td></tr>
<tr><td>Возможность слэшинга</td><td>Смарт‑контракт реализует правила автоматически</td><td>Оператор применяет правила вручную/автоматизированно</td></tr>
</table>
<h3>Как стейк связан с KYC/AML и лимитами выплат</h3>
<p class="foot">Стейк часто комбинируется с KYC: например, базовый стейк даёт доступ к внутриигровым выплатам, но чтобы вывести средства в CBDC/фиат выше порога — требуется KYC. Это уменьшает риск отмывания средств: крупные выплаты привязаны к верифицированным личностям.</p>
<h3>Antifraud: как именно стейк снижает риски</h3>
<ul>
<li>Экономический барьер для ботов — затратность создания множества аккаунтов.</li>
<li>При подозрительном поведении стейк можно временно заморозить и начать расследование.</li>
<li>Стейк используется как часть схемы залога при dispute — проигравшая сторона теряет часть стейка.</li>
</ul>
<h3>Экономика и влияние на геймдизайн</h3>
<p class="foot">Стейк влияет на мотивацию игроков: он делает участие более серьёзным и может снизить casual‑активность. Рекомендуется гибридный подход: минимальный обязательный стейк (low entry) и дополнительный voluntary stake для получения бонусов.</p>
<h3>Рекомендации по параметрам (пример)</h3>
<ul>
<li>Минимальный стейк для eligibility на вывод: эквивалент 1–5 USD (в токенах или CBDC), в зависимости от экономики игры.</li>
<li>Unbonding period: 24–72 часа для custodial, 7–14 дней для on‑chain (чтобы избежать мгновенных флудингов).</li>
<li>Slashing policy: небольшая комиссия (5–20%) при доказанном fraud; полное слэш‑удаление только при грубом нарушении.</li>
<li>Порог KYC: вывести > 50 USD требует KYC (пример — настройка по юрисдикции).</li>
</ul>
<h3>Пример интерфейса API для stake (Server)</h3>
<pre class="code">POST /api/v1/stake/deposit
Body: { "player_id":"did:player:abc","amount":10.0,"currency":"GRD" }
Response: 200 { "stake_id":"stk_123","status":"locked","unlock_at":"2025-09-01T00:00:00Z" }
POST /api/v1/stake/withdraw
Body: { "player_id":"did:player:abc","stake_id":"stk_123" }
Response: 202 { "status":"pending_unbond","expected_release":"2025-09-03T00:00:00Z" }
GET /api/v1/stake/status?player_id=did:player:abc
Response: 200 { "total_staked":10.0, "locked":10.0, "available":0.0 }
</pre>
<h3>Smart‑contract пример (Solidity, упрощённо)</h3>
<pre class="code">pragma solidity ^0.8.0;
contract SimpleStake {
mapping(address => uint256) public stakes;
function deposit() external payable { stakes[msg.sender] += msg.value; }
function withdraw(uint256 amount) external { require(stakes[msg.sender] >= amount, "insufficient"); stakes[msg.sender] -= amount; payable(msg.sender).transfer(amount); }
}
</pre>
<h3>Учёт и отчётность</h3>
<p class="foot">Стейк должен отражаться в accounting: frozen funds, liabilities, and collateral reserves. Для custodial‑стейка требуется реестр владельцев и audit trail, для on‑chain стейка — ссылки на tx hashes и контракт‑состояние.</p>
<h3>Юридические и регуляторные аспекты</h3>
<p class="foot">Стейк может быть классифицирован как привлечённые средства в ряде юрисдикций. Это влияет на бухгалтерию и лицензирование — заранее проконсультируйтесь с юристами и регуляторами.</p>
<h3>UX — как показать стейк игроку</h3>
<ul>
<li>Показывайте понятные статусы: <code class="inline">locked</code>, <code class="inline">available</code>, <code class="inline">pending_unbond</code>, <code class="inline">slashed</code>.</li>
<li>Отображайте ETA разблокировки и историю операций (депозиты, попытки вывода, слэш‑операции).</li>
<li>Объясняйте причину блокировки или штрафа — это снижает нагрузку в поддержку.</li>
</ul>
<h3>Заключение</h3>
<p class="foot">Стейк — гибкий инструмент управления рисками и стимулов. Его дизайн должен быть тщательно продуман в контексте экономики игры, юридических требований и UX. Рекомендуется начать с простого custodial‑стейка и постепенно вводить on‑chain механики после аудита и пилота.</p>
</section>
<section id="recommendations">
<h2>Рекомендации по использованию MAX и сопутствующих сервисов</h2>
<ul>
<li>Используйте MAX как главный identity-provider в РФ: ESIA-backed verification + DID для подписи событий.</li>
<li>Для массовых выплат используйте комбинацию HSM + multisig + ЭЦП через UC (через MAX или отдельный UC-провайдер).</li>
<li>Внедрите пороговую модель выплат: малая часть rewards — instant (in-game balance), крупные выплаты — после KYC и ручной/полуавтоматической проверки.</li>
<li>Подписывайте webhooks и храните audit trail в immutable store (append-only logs) для соответствия аудиту.</li>
<li>Обеспечьте opt-in для продажи телеметрических данных и применяйте differential privacy перед экспортом в marketplace (Filecoin/IPFS).
</ul>
</section>
<section id="faq">
<h2>Частые вопросы</h2>
<h3>Как происходит конвертация курсов?</h3>
<p class="foot">Gateway использует доверенные источники курсов (exchangerate.host, CoinGecko). В production рекомендуется проксировать запросы через ваш backend и кэшировать курсы.</p>
<h3>Кто платит игрокам?</h3>
<p class="foot">Плательщик зависит от сценария: частная компания (бюджет проекта), бренд (ad Task), государство (грант / программа) или маркеплейс (revenue split).</p>
</section>
<section>
<h2>Резюме и рекомендации</h2>
<ul>
<li>Начните с sandbox, используйте event_id для идемпотентности.</li>
<li>Скрывайте секреты на сервере, все клиентские ключи — одноразовые/ограниченные.</li>
<li>Настройте KYC/AML и отчётность для бизнес/гос интеграций.</li>
<li>Разработайте политики anti‑fraud и мониторинг по метрикам.</li>
</ul>
</section>
<footer class="foot" style="margin-top:18px">Документация сгенерирована автоматически <!-- при необходимости могу расширить разделы: подробные API‑контракты для EMTECH, цифрового рубля, примеры smart‑contracts и CI/CD сценарии по деплою. --> </footer>
</main>
</div>
</div>
</body>
</html>