Процесс онбординга

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

​

Что такое онбординг

Онбординг в Holders — это структурированный процесс интеграции пользователя мобильного кошелька с функциональностью Holders SDK. В рамках этого процесса пользователь создает персональный профиль Holders, предоставляет необходимые согласия на обработку данных и выполняет главное целевое действие — пополнение счета, чтобы получить полный доступ к функциональности Holders внутри кошелька.

​

Цели онбординга

• Объяснить ценность Holders

Пользователь понимает, что такое Holders, может оценить процесс онбординга и сформировать корректное представление о компании.

• Провести через создание профиля

Пользователь безошибочно проходит шаги: создает профиль, подтверждает подключение кошелька и завершает базовую настройку.

• Собрать необходимые согласия и разрешения

Пользователь предоставляет все обязательные согласия, как для Holders, так и для партнеров, чтобы сервис мог полноценно работать и оставаться compliant.

• Довести до первого целевого действия

Пользователь выполняет первое ключевое действие в Holders — создает и пополняет счет.

• Снизить отток и недопонимание

Нужно минимизировать случаи, когда пользователь выходит из онбординга из-за страха, непонимания или ощущения сложности, используя простые объяснения и понятные шаги.

• Отфильтровать неподходящих пользователей

Если пользователь не соответствует критическим условиям, например по резидентству или кредитоспособности, онбординг должен быть корректно остановлен с пояснением причин и, если это уместно, дальнейших действий.

​

Условия начала и завершения онбординга

​

Начало онбординга

Онбординг начинается на главной странице мобильного кошелька или приложения, в которое встроен Holders, обычно с показа баннера или pop-up окна с предложением открыть счет и выпустить карту. Баннер по умолчанию показывается всем пользователям приложения вне зависимости от их резидентства.
Баннер или окно отображаются на языке, выбранном пользователем как основной в мобильном приложении.

​

Завершение онбординга

Онбординг считается завершенным, если пользователь успешно пополнил свой счет в системе Holders. Во всех остальных случаях он считается незавершенным.

​

Схема онбординга

​

Основные этапы

1. Подключение кошелька — выполняется автоматически в фоне через протокол Ton Connect или адаптер для блокчейна Solana.
2. Создание user token — процедура передачи идентификационных данных на серверную сторону Holders.
3. Создание профиля — выполняется после подтверждения пользователем номера мобильного телефона. На этом этапе в базе Holders создается первичная запись.
4. KYC — процедура верификации пользователя через партнерский сервис, например Sumsub.
5. Создание аккаунта — деплой смарт-контракта и выпуск первой карты, если выполнены требования по резидентству.
6. Пополнение аккаунта — перевод средств на созданный счет.

​

Подробнее о подключении кошелька

Tonhub использует один криптографический ключ, то есть Ed25519, для работы сразу с двумя сетями: TON и Solana. Это возможно потому, что обе сети используют одинаковый алгоритм подписи.

​

Подключение TON

​

Процесс подключения

1. Получение manifest приложения — Tonhub загружает TonConnect manifest с сервера Holders, то есть /jsons/tonconnect-manifest.json, в котором указаны имя приложения, URL и иконка.
2. Аутентификация пользователя — пользователь подтверждает операцию с помощью биометрии или PIN-кода, чтобы дать доступ к секретному ключу кошелька.
3. Создание TON Proof — формируется криптографическое доказательство владения кошельком:
   • адрес кошелька берется в формате workchain:hash,
   • добавляется домен Holders, например tonhub.holders.io,
   • добавляется текущий timestamp,
   • добавляется payload, то есть случайная строка от сервера,
   • все это хэшируется и подписывается секретным ключом кошелька.
4. Отправка на сервер — выполняется POST-запрос на /v2/user/wallet/connect с данными:
   • адрес кошелька,
   • stack: 'ton',
   • network: 'ton-mainnet' или 'ton-testnet',
   • wallet: 'tonhub',
   • TON Proof, то есть timestamp, domain, signature, payload,
   • публичный ключ,
   • Wallet StateInit для верификации адреса.
5. Получение токена — сервер Holders проверяет подпись и возвращает User Token, то есть JWT.

​

Что проверяет сервер

• корректность подписи, то есть что она сделана владельцем указанного адреса;
• соответствие публичного ключа адресу через StateInit;
• актуальность timestamp, чтобы защититься от replay-атак;
• корректность домена.

​

Подключение Solana

​

Ключевая особенность

Tonhub использует тот же самый ключ Ed25519 для Solana, что и для TON. Это возможно потому, что:

• TON и Solana используют один и тот же алгоритм подписи, то есть Ed25519;
• публичный ключ TON-кошелька напрямую преобразуется в Solana-адрес.

​

Процесс подключения

1. Получение Solana-адреса — публичный ключ TON-кошелька, длиной 32 байта, интерпретируется как Solana PublicKey и преобразуется в формат Base58.
2. Создание Solana Proof — формируется аналогично TON Proof:
   • берется Solana-адрес, то есть публичный ключ в Base58,
   • добавляется домен Holders,
   • добавляется timestamp,
   • добавляется payload,
   • все подписывается тем же секретным ключом,
   • разница в том, что подпись кодируется в Base58, а не в Base64, как в TON.
3. Отправка на сервер — одновременно с TON отправляется и Solana proof:
   • Solana-адрес, то есть публичный ключ в Base58,
   • Solana Proof,
   • stack: 'solana',
   • network: 'solana-mainnet' или 'solana-devnet'.

​

Результат

Сервер Holders связывает оба аккаунта, TON и Solana, с одним пользователем и выдает единый User Token для доступа к обоим.

​

Что такое User Token

User Token — это JWT, JSON Web Token, который выдается сервером Holders после успешной аутентификации и служит идентификатором пользовательской сессии.

​

Для чего он используется

Функция	Определение
Авторизация в API	Передается в каждом запросе к Holders API в теле запроса, например { token: "..." }
Получение профиля	/v2/profile/get — информация о пользователе
Список аккаунтов	/v2/account/list — карты и криптовалютные аккаунты
Статус аккаунта	/account/state — статус KYC и верификации
OTP-запросы	/v2/user/otp/requests — одноразовые пароли для операций
WebSocket	Подключение к wss://*/v2/updates для обновлений в реальном времени

​

Где он хранится

• Токен сохраняется локально в защищенном storage устройства, например MMKV.
• Он привязан к конкретному TON-адресу кошелька.

​

Когда он удаляется

1. Ответ 401 от API — токен истек или стал недействительным.
2. Новый invite code — при повторной попытке регистрации по приглашению.
3. Миграция — при обновлении формата токена, например при переходе на объединенный TON + Solana.

После первичной аутентификации и получения User Token основное взаимодействие с Holders происходит через WebView со встроенным JavaScript Bridge.

​

Метрики и аналитика

Процесс онбординга пользователя покрывается метриками и на frontend, и на backend. Backend-события отправляются в Backoffice, а также в сервис Metabase. Frontend-события можно смотреть и строить по ним воронки в сервисе Mixpanel.