Сервис Calcium WebAPI для работы с блокчейнами

Calcium нояб. 08, 2021

Что такое Calcium: Network, Library, WebAPI

Команда UFO разрабатывает децентрализованную сеть Calcium.Network, которая включает в себя несколько подпроектов, таких как криптокошелек Walletum, блог-платформа Slabber и бэкенд для доступа к блокчейнам Calcium WebAPI.

Задача доступа к разным блокчейнам через единый интерфейс решена через реализацию опен-сорс библиотеки Calcium Library. По состоянию на конец 2021 года библиотека все еще в фазе активной разработки и доступна ограниченному кругу core разработчиков, поддерживаются монеты UFO, токены UniAsset (UFO), BTC, LTC, USDT Omni (Bitcoin), в разработке поддержка ETH и ERC20 токенов.

В библиотеке Calcium Library предусмотрены как множество примитивов для работы с разными блокчейнами, так и высокоуровневые объекты для работы с аккаунтами и кошельками. В библиотеку закладываются элементы, которые позволят в будущем подключаться и взаимодействовать с сетью Calcium.Network, использовать кошелек Walletum (или схожее приложение) в качестве авторизатора и т. д. Помимо этого, реализован ряд инструментов, позволяющих разрабатывать кросс-платформенные приложения с поддержкой мобильных и веб-платформ, а, в перспективе, и полноценные десктоп приложения.

Библиотека разработана на языке Typescript, что требует определенных дополнительных усилий для ее интеграции в другие языки программирования и платформы, помимо nodejs и веба.

Для упрощения жизни разработчикам командой разработан онлайн-сервис Calcium WebAPI (https://clwebapi-regtest.calcium.cloud/), который предоставляет интерфейс разработчика и простой JSON RPC интерфейс для работы со всеми поддерживаемыми библиотекой блокчейнами.

По состоянию на ноябрь 2021 года сервис доступен в режиме регтест-сети для разработки бч-приложений в режиме тестовых монет. Поддержка mainnet сети запланирована на конец 2021 года.

Как устроен Calcium WebAPI

Calcium WebAPI предоставляет HTTP и Websocket интерфейсы для вызова JSON RPC функций.

Запросы к сервису должны выполняться с использованием токена серверной авторизации, который создается в интерфейсе учетной записи разработчка:

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

Онлайн документация по функциям Calcium WebAPI готовится и будет доступна по ссылке https://clwebapi-regtest.calcium.cloud/reference.

Помимо этого, интерфейс разработчика предоставляет playgroud - полный список доступных функций API, с описанием входных параметров и возможностью вызвать функцию прямо из интерфейса разработчика и увидеть результат ее работы.

Важное уточнение про некоторые термины

Везде по тексту мы используем два термина:
«учетная запись разработчика» - для обозначения вашего доступа в интерфейс разработчика Calcium WebAPI через браузер.
«аккаунт» - обозначает набор настроек и кошельков, созданных программно через вызовы функций AccountManager.Create...Account, которыми вы будете пользоваться из своего приложения через API.

Пожалуйста, не забывайте про это. Это важно!

Архитектура аккаунтов и кошельков Структура взаимодействия

Архитектура Calcium WebAPI предполагает, что для вашего приложения может быть использован один или несколько аккаунтов, в рамках которых создается коллекция крипто- кошельков для разных валют. В зависимости от вида блокчейна, кошельки могут работать в режиме одного адреса или в hd-режиме.

Как лучше организовать данные в вашем приложении Схема «Один ваш пользователь — один аккаунт»

Подходит, когда каждому вашему пользователю нужен полноценный набор кошельков, не пересекающийся с кошельками других ваших пользователей. Т.е. либо ваше приложение на устройстве пользователя самостоятельно общается с Calcium WebAPI, либо ваш серверный бэкенд умеет четко разделять пользователей и сопоставлять их с аккаунтами.

Для каждого вашего нового пользователя регистрируется новый аккаунт через вызов функции AccountManager.CreateLocalAccount.
Активация аккаунта происходит через вызовы Account.Connect в моменты, когда пользователь в вашем приложении становится активен и ему необходим доступ к кошелькам. При отключении пользователя рекомендуется использовать метод Account.Disconnect.

Плюсы: четкая организация данных, разделение средств. Минусы: задействуется больше ресурсов сервиса.

Схема «Один аккаунт для бэкенда».

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

Плюсы: минимальная нагрузка на сервис.
Минусы: нет разделения средств, отдельной «бухгалтерии».

Объективные ограничения

Помимо обслуживания JSON RPC запросов разработчиков, работа сервиса во многом связана с постоянной фоновой обработкой данных нескольких блокчейнов. Сервис обеспечивает сканирование как единичных адресов, так и цепочек HD адресов разных стандартов. Его задача - предоставить множеству пользователей наиболее актуальные и оперативные данные по балансам, доступным входами и истории транзакций.

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

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

Подключение к Calcium WebAPI

Используйте библиотеку JSON RPC для вашего языка программирования. Интерфейсы сервиса доступны в виде:

• HTTP https://clwebapi-regtest.calcium.cloud/api/1/json-rpc

• Websocket https://clwebapi-regtest.calcium.cloud/api/1/ws

При установке соединения необходимо задать http-хидер авторизации:
Authorization: Bearer: ТОКЕН_ИЗ_ВЕБ_ИНТЕРФЕЙСА_РАЗРАБОТЧИКА

Актуальная версия RPC схемы со списком методов и описанием параметров:
https://clwebapi-regtest.calcium.cloud/api/1/OpenRPC_GetSchema

Формат RPC и типы данных

пример rpc вызова:
пример rpc ответа:
{ "jsonrpc": "2.0", "method": "accountmanager.getsnapshot", "params": { "accountid": "0" },"id": 3 } { "jsonrpc": "2.0", "id": 3, "result": { "updating": false, "accounts": { "0": { "id": "0", "title": "my acc", "online": false, "remote": false, "collections": {} } } } }

В описании RPC схемы Calcium WebAPI в параметрых функций и возвращаемых результатах в некоторых случаях указаны типы данных Typescript, используемые внутри библиотеки Calcium Library TS. Такие типы являются простыми (строки, числа) или составными (объекты, массивы) стандартными JSON типами и могут быть распарсены любым стандартным JSON парсером.

В блокчейнах требуется большая разрядность для хранения челочисленных значений в минимальных единицах (сатошах и аналогах).
По это причине RPC ответы будут содержать числовые значения в сатошах в экспоненциальной записи вида «100000000000e-8», что обозначает размерность монеты в 8 знаков (100 млн. сатоши), а значение эквивалентно сдвигу запятой на 8 символов влево, т. е. 1000 сатоши.

Стандартные JSON парсеры должны распознавать данный формат без проблем, однако значения с 16 и более значащими цифрами теряют свою точность в некоторых языках программирования (например, javascript). Что может приводить к ошибкам при суммировании или проверках в вашем программном обеспечении.

Безопасность vs. кастодиальность

На данный момент сервис Calcium WebAPI предоставляет только кастодиальный способ хранения средств, когда приватные ключи хранятся в шифрованном виде в базе данных сервиса. Разработчик может создавать локальные (для сервиса) аккаунты через вызов AccountManager.CreateLocalAccount.

Для хранения данных внутри сервиса используется слой шифрования на уровне учетной записи разработчика. Помимо этого, мы настоятельно рекомендуем использовать пароли аккаунтов при создании и подключении. В этом случае, данные аккаунта шифруются дополнительно указанным паролем, а расшифрованным аккаунт остается только на время его активности (Account.Connect/Account.Disconnect).

Дополнительная рекомендация — периодически производить бэкап сид-фраз созданных аккаунтов и приватных ключей используемых кошельков с помощью метода Account.Backup. Это позволит вам получить экстренный доступ к вашим средствам через стороннее ПО в случае недоступности сервиса.

В дальнейших планах - возможность создания удаленных (для сервиса) аккаунтов — для реализации некастодиального режима работы. В таком режиме сервис обеспечивает администрирование аккаунтов и кошельков, сканирование данных блокчейнов, однако не хранит приватные ключи, и, соответственно, не имеет доступа к средствам. Приложению разработчика необходимо будет реализовать дополнительный протокол обратной связи и самому озаботиться безопасным хранением приватных ключей.

Стабильность API

Несмотря на большой объем проделанной работы по разработке, сервис Calcium WebAPI находится в самом начале своего пути. До запуска mainnet версии возможны изменения в наборе функций, параметрах их вызовов.

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

Тем не менее, просим отнестись с пониманием к тому, что проект на данный момент не предоставляет коммерческого сервиса. Сервис предоставляется AS IS без гарантий. В бесплатном режиме его использования пользователем, команда не имеет возможности обеспечивать полноценную техническую поддержку и какой-либо SLA.

Если Calcium WebAPI вам интересен для интеграции и вы хотели бы получить коммерческие услуги — напишите нам на pr@ufobject.com

Ссылки

Calcium WebAPI интерфейсы:

Calcium WebAPI JSON RPC:

Телеграмм группы:

Что почитать об UFO и Calcium:

Теги