Safina API

h4. Начало работы

p(. Базовым идентификатором пользователя со стороны API является хэш публичного ключа из пары ключей, полученных с помощью алгоритма эллиптических кривых (Elliptic Curve SECP256k1). Хэш публичного ключа это так называемый "адрес", поле [[WIKI#API|x-app-ec-from]] в запросе, который выступает в роли электронной подписи.

{{collapse(Вспомогательная информация - важно!)

p(. Алгоритм подписи: "EC" - эллиптические кривые Elliptic Curve SECP-256k1 (https://habr.com/ru/post/692842/ или на английском https://habr.com/ru/post/692072/).

Для проверки механизма подписи можно вызывать простейший запрос GET https://my.h2k.me/ec/netlist/1, который в случае успешной проверки вернёт список активных сетей в системе.

}}

h4. Обращение к API

p(. Чтобы обратиться к API, обязательно требуется наличие трёх полей электронной подписи запроса ([[WIKI#API|x-app-ec-sign-r, x-app-ec-sign-s, x-app-ec-sign-v]]) в заголовках запросов. Подписывается URL запроса и поля формы (если это POST запрос).

После вызова функции API, создающей кошелёк, *все последующие команды* для работы с этим кошельком требуют электронной подписи именно теми ключами, которые были использованы для подписи команды на создание кошелька.

h4. Безопасность

p(. Для одной пары ключей (одного условного пользователя) можно создавать несколько кошельков, каждый кошелёк получает свой уникальный код ([[WIKI#Получение-списка-кошельков|получение списка кошельков]]).

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

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

---

p(. Важно помнить, что пара ключей открывает возможность тратить средства, находящиеся на кошельках, которые созданы с помощью этой пары. Поэтому необходимо обеспечить безопасное хранение этой пары.

Существует несколько общедоступных библиотек, которые реализуют функции по созданию ключей, вычислению подписи и проверке подписи  ().

Для того, чтобы было удобно восстанавливать пару ключей, можно воспользоваться механизмом их генерации с использованием SID фразы (набора слов, обычно 12 или 24 слова, https://habr.com/ru/company/distributedlab/blog/413627/).

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

p(. Особенности некоторых библиотек, предназначенных для работы с блокчейн сетями: модификация подписываемого сообщения, что не нужно в нашем случае (https://github.com/web3j/web3j/issues/208)

---

p=. *ВАЖНО!*

p(. Данные ключи не используются самой системой для работы с блокчейн сетями. Для каждого создаваемого кошелька система генерирует собственные ключи и уже их использует для работы с блокчейн сетями.

---

h4. Примерный порядок работы с API

p(. Предварительно необходимо получить справочника блокчейн сетей, чтобы указывать ID сети при создании кошелька. 

p(. Также, доступен справочник поддерживаемых системой токенов с параметрами комиссий системы - запрос "Получение справочника токенов"

p(. Следующий шаг - создание кошелька. При создании кошелька кроме указания ID блокчен сети нужно ещё указать параметры "мультиподписи" - какое минимальное количество подписантов должно подписать и описание самих подписантов.

Каждый подписант имеет возможность подписывать как условными подписями (ссылкой-кодом полученным на его email, кодом из смс уведомления, отправленного на телефон) или электронным ключём). Дополнительно указывается нужно ли использовать все указанные у подписанта способы или только один из них.

Время создания кошелька может составлять 10 минут с момента получения последней необходимой подписи.

p(. Для получения информации по созданным кошелькам нужно выполнить операцию получения списка кошельков. Каждый из кошельков в списке будет содержать собственный адрес

p(. При создании кошелька система также добавляет пользователю базовый токен блокчейн сети кошелька с балансом "0". Периодически система проверяет баланс кошелька и обновляет баланс и список токенов которые содержаться на данном кошельке. Получить список токенов и балансы можно командой "Получение списка токенов пользователя с одного кошелька" либо "Получение списка всех токенов пользователя"

p(.