Octo Rewards — Документация интеграции

Обзор

Octo Rewards — модульный шлюз вознаграждений для игр и приложений.
Позволяет начислять игрокам материальные вознаграждения за прогресс и время игры через различные каналы:
CBDC (e‑Cedi, цифровой рубль), ончейн токены (ERC‑20 / EVM), и продажу анонимных наборов данных (маркетплейс).

Ключевые понятия

• Gateway — центральный компонент: принимает события от клиента, рассчитывает вознаграждение и отправляет команду на settlement adapter.
• Settlement Adapter — адаптер к конкретной системе выплат (CBDC API, blockchain RPC, marketplace API).
• Event — структурированное сообщение о прогрессе игрока (time_played, milestone, task_completed).
• Rules Engine — конфигурируемая логика расчёта выплат (pay per hour, milestone rewards, diminishing returns, governance multipliers).

Поддерживаемые интеграции

Архитектура

Единая архитектура позволяет подключать Gateway как API в любую игру или приложение. Стек типично включает клиентские SDK, backend-интегратор, Rules Engine и множество Settlement Adapter'ов.

Компоненты

Простой поток событий (sequence)

1. Клиент отправляет Event → Gateway (HTTPS POST или websocket)
2. Gateway валидирует событие, проверяет подпись
3. Rules Engine рассчитывает сумму и проверяет лимиты/KYC
4. Создаётся транзакция в Settlement Adapter
5. Settlement Adapter подтверждает выполнение — Accounting обновляет статус

JSON example: Event schema

{
  "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"
}

Подпись — опциональна, но обязательна для high-value выплат; используется сервисный ключ или DID-подпись клиента.

API & Форматы

1) Приём событий — POST /api/v1/events

POST /api/v1/events
Content-Type: application/json
Authorization: Bearer <gateway-api-key>

{ ... event as above ... }

Response 202 Accepted
{ "ingest_id":"uuid", "status":"queued" }

2) Webhook callback (async result)

POST /webhooks/rewards
Headers: X-Signature: hmac_sha256(<secret>, body)

{ "ingest_id":"uuid","settlement_status":"settled","tx_ref":"ecedi-12345","amount":0.5 }

3) Управление правилами (Admin)

GET /admin/rules
POST /admin/rules  { name: 'payPerHour', value: 0.1 }

Примеры клиентской отправки (JavaScript)

// Простой пример отправки события через 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);

Server-side: Webhook verification (Node/Express)

// 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});
});

Idempotency и повторная обработка

Каждое событие должно иметь уникальный event_id. Gateway гарантирует at-least-once delivery для Adapter'ов; Settlement Adapter должен быть идемпотентным (используйте ingest_id или event_id в качестве idempotency key).

Примеры интеграции по платформам

Веб (Browser)

Подключите клиентский SDK/просто используйте fetch. Для on-chain выплат интегрируйте MetaMask / WalletConnect.

// Пример отправки события и запроса на выплату через сервера
// Клиент -> Gateway: POST /api/v1/events
// Gateway -> Rules Engine -> Settlement Adapter -> (EMTECH/Blockchain)

Mobile: iOS / Android / React Native

Используйте native HTTP client; для on-chain интеграции используйте WalletConnect 2.0 для мобильных кошельков.

// 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(...)
*/

Unity (C#)

В Unity используйте UnityWebRequest для отправки событий и подписи через native plugin, если нужен secure enclave.

// Unity C# — отправка простого события
/*
using UnityEngine.Networking;
var evt = JsonUtility.ToJson(yourEvent);
UnityWebRequest.Post("https://gateway.example.com/api/v1/events", evt);
*/

Game engines — общие рекомендации

• Клиент отправляет только события; бизнес-логика расчёта выплат выполняется на сервере.
• Минимизируйте привязку секретов к клиенту — используйте transient tokens и server-side signing.
• Поддерживайте оффлайн-очередь и ретрай — сетевые прерывания в играх обычны.

Backend: Node / Python / Java / Go

При реализации Settlement Adapter'ов используйте проверенные SDK и HTTP clients; следите за retry, circuit breaker и idempotency.

On-chain example (ethers.js) — mint & transfer

// 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));

Smart contract (Solidity) — простой mintable ERC20

// 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); }
}

Интеграция: Частная, Бизнес, Государство

Частные интеграции (инди-разработчики и малые студии)

• Используйте gateway sandbox key, lightweight KYC (если выплаты < threshold).
• Примеры: внутриигровые микровыплаты для мобильных игр, платные подписки с выплатой за время.
• Требования по audit: базовый логинг, экспорт журнала транзакций.

Бизнес (коммерческие студии и платформы)

• Интеграция с бухгалтерией и налоговыми отчётами, SLA, SLA‑monitoring для выплат, KYC/AML партнёрство.
• Обычно нужен серверный агрегатор (middleware) — чтобы скрывать секреты и управлять очередями выплат.

Гос. органы / публичные проекты

• Строгое соответствие нормативам, требование audit trail, подробный регламент доступа и межведомственное взаимодействие.
• Интеграция с CBDC API (как EMTECH) через официальный sandbox и подписанные API‑ключи, регулярные проверки безопасности.

Таблица сравнения требований

Безопасность, соответствие и операции

1. Аутентификация и авторизация

• API Keys: строгие права (scopes) — разделяйте write/read/admin.
• Webhook secret: HMAC signature для проверки источника.
• Для on-chain: используйте безопасное хранение приватных ключей (HSM / KMS).

2. Подписи и доказательства

Для high-value транзакций требуется cryptographic proof: DID‑подпись, JWT signed by client, или service-side signed request.

3. KYC/AML

Интеграция со сторонними провайдерами KYC (Jumio, Onfido и т.п.) по необходимости. Threshold для KYC настраивается в Rules Engine.

4. Anti‑fraud

• Rate limits и anomaly detection (странные паттерны сессий).
• Детектирование мультиаккаунтов и временных паттернов (анти-bot).
• Автоматические блокировки по правилам.

5. Compliance & Logging

• Все транзакции логировать: event_id, ingest_id, settlement_id, timestamps, responsible_actor.
• Хранение audit trail минимум 5 лет — зависит от юрисдикции.

Тестирование и деплой

Sandbox режим

Всегда начинайте с sandbox адаптеров (EMTECH sandbox, testnet для блокчейнов). В sandbox можно тестировать без реальных сущностей.

Набор тестов

• Unit tests: Rules Engine расчёты (payPerHour, milestone)
• Integration tests: Gateway → Adapter (mock сервера)
• End-to-end: Клиент → Gateway → Settlement → Webhook

Пример теста (Node + Mocha + Supertest)

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);
  });
});

Мониторинг

• Метрики: latency (gateway/adapters), success_rate, payout_volume
• Алерты: повышенная ошибка адаптера, queue backlog, необычный spike в выплатах

Экономика и модели монетизации

Ниже — типовые модели монетизации и примеры расчёта.

Модели

1. Pay‑per‑time — выплата за проведённое время (например 0.10 USD за 60 минут)
2. Milestone — фиксированная выплата за достижения (уровень, миссия)
3. Revenue share / Data sale — доход от продажи анонимных данных распределяется между игроками

Пример распределения (Data marketplace)

Если набор данных продан за 100 USD и договорено, что игроки получают 60%:

revenue = 100
players_pool = 0.6 * revenue = 60
player_share = (player_contrib / total_contrib) * players_pool

Архитектура (напоминание)

Единая архитектура: Client SDK → Gateway → Rules Engine → Settlement Adapters → Accounting / Webhooks. Мощный пункт — интеграция провайдеров идентификации и подписи (MAX, Госуслуги/ЕСИА, удостоверяющие центры) для надёжного KYC/Legal signing.

Поток событий

1. Client отправляет Event (POST / websocket) — опционально подписывает события DID-подписью
2. Gateway валидирует подпись + payload
3. Rules Engine вычисляет reward, проверяет лимиты и уровень KYC
4. Settlement Adapter инициирует выплату (CBDC API / on-chain tx / marketplace sale)
5. Accounting логирует и отправляет webhook результат

Интеграция с мессенджером MAX — возможности и сценарии

MAX можно использовать как идентификационный и подписиный шлюз: он облегчает KYC/AML, предоставляет DID-подписи и поддерживает цифровые сервисные ключи (ЭП/ЭЦП). Ниже — практические сценарии и архитектурные рекомендации.

Почему MAX помогает

• Готовая идентификация: MAX часто интегрирован с ЕСИА/Госуслугами и партнёрскими удостоверяющими центрами — это позволяет получать подтверждённые данные о личности.
• DID-подписи: MAX может выпускать DID-учётные записи, которые используются для подписания сообщений без раскрытия всех личных данных.
• ЭЦП/ЭП: сервис позволяет производить юридически значимые подписи (электронная подпись) или подписывать транзакции цифровым сервисным ключом организации.
• Удобство UX: встроенная авторизация через мессенджер снижает барьер входа для игроков.

Типовые сценарии с MAX

1) Быстрая регистрация и KYC

Игрок кликает «Войти через MAX». MAX возвращает утверждённый профиль (имя, дата рождения, подтверждённый email/телефон), а также статус верификации ESIA (при наличии). Gateway помечает пользователя как KYC-verified и разрешает higher-value payouts.

2) DID-подпись событий

Клиент получает DID-ключ в MAX и подписывает важные события (например, запрос на вывод средств). Gateway проверяет DID-подпись и обрабатывает запрос как авторизованный.

3) Подпись цифровым сервисным ключом (ЭЦП/ЭП)

Организация, интегрированная с MAX и удостоверяющим центром, может подписывать массовые batch‑выплаты юридически значимой ЭЦП. Это особенно важно в B2G сценариях и при передаче отчётности.

Архитектурный пример: MAX как Identity & Signing Gateway

Client (game) --auth--> MAX (OAuth/ESIA) --assertion--> Gateway
Client signs event with DID (MAX) --> Gateway validates DID
Gateway requests settlement --> Adapter подписывает batch с ЭЦП сервиса (через MAX/UC)

Ограничения и нюансы

• Наличие обязательств по хранению персональных данных: даже при использовании MAX вы должны соблюдать local privacy laws.
• Не все пользователи хотят привязывать мессенджер к игровому аккаунту — предложите альтернативы (email, social logins).
• Юридическая значимость ЭЦП требует согласования с удостоверяющим центром и регулятором.

Резюме по MAX

MAX существенно упрощает KYC/AML и подписи, особенно в российской экосистеме. Рекомендуется как primary identity provider для операций, где требуется подтверждённая юр. сила подписи.

API & Форматы (коротко)

Основные endpoint'ы: /api/v1/events (ingest), /admin/rules, webhook callbacks. См. отдельный файл с OpenAPI для полного контракта.

Глоссарий — термины и определения

KYC (Know Your Customer)

Процедуры верификации личности клиента: сбор документов (паспорт/ID), проверка через сторонние провайдеры (Jumio, Onfido) или государственные сервисы (ЕСИА/Госуслуги). Цель — убедиться, что пользователь — реальное лицо и оценить риск.

AML (Anti-Money Laundering)

Комплекс мер по противодействию отмыванию денег и финансированию терроризма: мониторинг транзакций, отчётность в FIU, тревожные флаги и блокировки.

DID (Decentralized Identifier) (ссылка)

Децентрализованный идентификатор — схема идентификации, где субъект имеет публичный DID и ассоциированные ключи. DID-подпись позволяет подтверждать происхождение данных без передачи всех персональных атрибутов.

ЭЦП / ЭП (электронная цифровая подпись / электронная подпись)

Юридически значимая подпись, подтверждаемая удостоверяющим центром (UC). В РФ часто используется термин ЭЦП. Используется для подписания юридически значимых документов и batch-платежей.

Антифрод (Anti-Fraud)

Система обнаружения мошенничества: правила, эвристики, ML-модели, поведенческая аналитика. Включает детекцию мультиаккаунтов, аномалий в метриках сессий и подозрительных паттернов выплат.

HSM (Hardware Security Module)

Аппаратный модуль безопасности для хранения приватных ключей. Рекомендуется для production custody ключей (как on-chain, так и для подписей ЭЦП).

Multisig / Multi‑party signing

Механизм, когда несколько ключей/партий должны подписать транзакцию; снижает риск одностороннего слива средств.

Idempotency key

Уникальный ключ для повторных вызовов API, чтобы предотвратить дублирование действий (например, двойные выплаты при retry).

Nonce / Sequence

Числовой счётчик, предотвращающий повторное воспроизведение транзакций в блокчейне или API.

Settlement Adapter

Компонент, реализующий интеграцию с конкретной системой выплат: CBDC API, blockchain RPC, PSP, marketplace.

ESIA / Госуслуги

Единая система идентификации и аутентификации в России. Интеграция с ESIA позволяет получать подтверждённые атрибуты личности у пользователей РФ.

FIU (Financial Intelligence Unit)

Национальный орган, который получает сообщения о подозрительных операциях и анализирует финансовые потоки (в РФ — Росфинмониторинг).

Filecoin / IPFS

Децентрализованные хранилища для больших наборов данных. Используются для безопасного хранения анонимизированных телеметрических наборов, которые затем продаются через marketplace.

Sandbox

Тестовая среда (EMTECH sandbox, CBDC тестовые конторы, blockchain testnets) для безопасной проверки интеграции без реальных средств.

UBO (Ultimate Beneficial Owner)

Конечный бенефициар компании — важно при KYC для юридических лиц.

Webhook

Callback URL, на который Gateway отправляет асинхронные уведомления о результатах settlement — подписываются HMAC для верификации.

Что такое «стейк» игрока в нашем контексте

В документации под стейком игрока мы понимаем сумму (денежную или в токенах), которую игрок блокирует в системе как гарантию поведения, квалифицирующее его на выплаты, привилегии или участие в governance. Стейк — это инструмент экономической и поведенческой дисциплины: он служит депозитом, репутационным сигналом и фильтром против злоупотреблений.

Основные роли и цели стейка

• Валидация доступа к выплатам: минимальный стейк может быть предикатом, позволяющим игроку выводить реальные средства или участвовать в high-value выплатах.
• Антифрод / Anti‑Sybil: стейк повышает стоимость массового создания фейковых аккаунтов (farm), так как для каждого аккаунта требуется капитал.
• Сигнал репутации: размер и возраст стейка используются в правилах начисления (чем выше стейк — тем больше доверие / бонус).
• Экономический коллатераль: стейк может блокироваться для покрытия штрафов, чарджбэков или компенсаций в случае нарушения правил.
• Governance и участие: стейк может давать голос в управлении параметрами Rules Engine (например, голосование за изменение payPerHour).

Механики стейкинга — как это реализуется

• Типы стейка: on‑chain (ERC‑20 / native token locked in smart contract) или custodial/off‑chain (средства хранятся у оператора и блокируются в учётной записи).
• Lock / Unlock: при депозите стейк переводится в статус locked на заданный период. После окончания периода доступен withdraw с ожиданием (unbonding).
• Slashing / Penalties: при нарушениях часть или весь стейк может быть изъят (slashed) согласно правилам (fraud detection, chargeback).
• Stake as collateral: стейк может быть резервом для immediate payouts — например, если у оператора временно нет возможности провести выплату в CBDC, он использует часть стейка как гарантию возврата.

On‑chain vs Custodial — плюсы и минусы

Как стейк связан с KYC/AML и лимитами выплат

Стейк часто комбинируется с KYC: например, базовый стейк даёт доступ к внутриигровым выплатам, но чтобы вывести средства в CBDC/фиат выше порога — требуется KYC. Это уменьшает риск отмывания средств: крупные выплаты привязаны к верифицированным личностям.

Antifraud: как именно стейк снижает риски

• Экономический барьер для ботов — затратность создания множества аккаунтов.
• При подозрительном поведении стейк можно временно заморозить и начать расследование.
• Стейк используется как часть схемы залога при dispute — проигравшая сторона теряет часть стейка.

Экономика и влияние на геймдизайн

Стейк влияет на мотивацию игроков: он делает участие более серьёзным и может снизить casual‑активность. Рекомендуется гибридный подход: минимальный обязательный стейк (low entry) и дополнительный voluntary stake для получения бонусов.

Рекомендации по параметрам (пример)

• Минимальный стейк для eligibility на вывод: эквивалент 1–5 USD (в токенах или CBDC), в зависимости от экономики игры.
• Unbonding period: 24–72 часа для custodial, 7–14 дней для on‑chain (чтобы избежать мгновенных флудингов).
• Slashing policy: небольшая комиссия (5–20%) при доказанном fraud; полное слэш‑удаление только при грубом нарушении.
• Порог KYC: вывести > 50 USD требует KYC (пример — настройка по юрисдикции).

Пример интерфейса API для stake (Server)

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 }

Smart‑contract пример (Solidity, упрощённо)

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); }
}

Учёт и отчётность

Стейк должен отражаться в accounting: frozen funds, liabilities, and collateral reserves. Для custodial‑стейка требуется реестр владельцев и audit trail, для on‑chain стейка — ссылки на tx hashes и контракт‑состояние.

Юридические и регуляторные аспекты

Стейк может быть классифицирован как привлечённые средства в ряде юрисдикций. Это влияет на бухгалтерию и лицензирование — заранее проконсультируйтесь с юристами и регуляторами.

UX — как показать стейк игроку

• Показывайте понятные статусы: locked, available, pending_unbond, slashed.
• Отображайте ETA разблокировки и историю операций (депозиты, попытки вывода, слэш‑операции).
• Объясняйте причину блокировки или штрафа — это снижает нагрузку в поддержку.

Заключение

Стейк — гибкий инструмент управления рисками и стимулов. Его дизайн должен быть тщательно продуман в контексте экономики игры, юридических требований и UX. Рекомендуется начать с простого custodial‑стейка и постепенно вводить on‑chain механики после аудита и пилота.

Рекомендации по использованию MAX и сопутствующих сервисов

• Используйте MAX как главный identity-provider в РФ: ESIA-backed verification + DID для подписи событий.
• Для массовых выплат используйте комбинацию HSM + multisig + ЭЦП через UC (через MAX или отдельный UC-провайдер).
• Внедрите пороговую модель выплат: малая часть rewards — instant (in-game balance), крупные выплаты — после KYC и ручной/полуавтоматической проверки.
• Подписывайте webhooks и храните audit trail в immutable store (append-only logs) для соответствия аудиту.
• Обеспечьте opt-in для продажи телеметрических данных и применяйте differential privacy перед экспортом в marketplace (Filecoin/IPFS).

Частые вопросы

Как происходит конвертация курсов?

Gateway использует доверенные источники курсов (exchangerate.host, CoinGecko). В production рекомендуется проксировать запросы через ваш backend и кэшировать курсы.

Кто платит игрокам?

Плательщик зависит от сценария: частная компания (бюджет проекта), бренд (ad Task), государство (грант / программа) или маркеплейс (revenue split).

Резюме и рекомендации

• Начните с sandbox, используйте event_id для идемпотентности.
• Скрывайте секреты на сервере, все клиентские ключи — одноразовые/ограниченные.
• Настройте KYC/AML и отчётность для бизнес/гос интеграций.
• Разработайте политики anti‑fraud и мониторинг по метрикам.