Плагины представляют собой универсальный инструмент расширения ноды и её возможностей. Часть из них лишь отдают данные, подготавливают индексы, отвечают на сложные запросы пользователей с фильтрацией данных, часть из них обрабатывают custom операции и могут предоставлять совершенно отдельный сервис.
В данном разделе описаны некоторые доступные плагины GOLOS, предоставляющие пользователям доступ через API. Вы можете сами изучить API того или иного плагина, если будете следовать следующей инструкции:
Открыть основной заголовочный файл плагина (пример для database_api), изучить DEFINE_API_ARGS (название API метода, тип возвращаемого значения);
Открыть основной файл плагина (пример для database_api), изучить DEFINE_API (проверка параметров запроса, CHECK_ARGS_COUNT, формирование возвращаемого значения определенного типа);
Изучить plugin_initialize, который может обрабатывать boost::program_options::variables_map для более тонкой настройки плагина через конфигурационный файл ноды.
Протокол запросов
Все запросы должны быть сформированы в JSON и выполнены через RPC. Транспортный протокол зависит от настройки ноды, возможны варианты как JSON-RPC через стандартные HTTP запросы, так и через WebSocket.
Для этого в конфигурационном файле ноды должны быть подключены плагины: json_rpc, webserver. Чтобы принимать транзакции от пользователей также должен быть включен плагин network_broadcast_api. Настройки для портов:
# Количество потоков для клиентов rpc. Оптимальное значение *количество ядер минус 1*
webserver-thread-pool-size = 2
# IP:PORT для HTTP подключений
webserver-http-endpoint = 0.0.0.0:8090
# IP:PORT для WebSocket подключений
webserver-ws-endpoint = 0.0.0.0:8091
Чтобы обрабатывать запросы с поддержкой SSL, необходимо пробросить используемые порты через проксирующий сервер (например, nginx или apache), тогда станут возможными запросы через https/wss.
Формирование API запроса
Правила формирования запросов к публичной ноде довольно простые:
REQUEST_ID — номер запроса, носит необязательный характер (можно все запросы нумеровать единицей), но при соединении через web sockets (ws) позволяет ассоциировать ответы по запросам с аналогичным id;
PLUGIN_NAME — название плагина, к которому выполняется запрос (например: database_api, committee_api);
PLUGIN_API_METHOD — название метода, обрабатывающего запрос (например: get_accounts из database_api);
ARGS — массив упорядоченных параметров, передаваемый методу плагина.
network_broadcast_api
Плагин, отвечающий за прием и рассылку между узлами сети подписанных блоков и транзакций
broadcast_block — передача подписанного блока (signed_block) другим узлам сети;
broadcast_transaction — передача подписанной транзакции (signed_transaction) другим узлам сети;
broadcast_transaction_synchronous — передача подписанной транзакции (signed_transaction) другим узлам сети (ждет вхождения в блок и возвращает хэш транзакции, номер блока и номер транзакции в блоке, или возвращает false в случае истечения срока действия транзакции);
broadcast_transaction_with_callback — то же, что и broadcast_transaction_synchronous, кроме проверки транзакции на валидность перед передачей в пул транзакций и регистрации метода обратного вызова (callback).
database_api
get_account_count — возвращает количество аккаунтов в сети;
get_accounts — возвращает массив аккаунтов по запрошенным логинам (отличается от lookup_account_names дополнительной информацией);
get_escrow — возвращает информацию о трехсторонней сделке по логину аккаунта и идентификатору сделки (id);
get_expiring_vesting_delegations — возвращает список возвращаемой делегированной доли (по времени истечения возврата);
get_hardfork_version — возвращает версию текущего хардфорка;
get_next_scheduled_hardfork — возвращает следующий запланированный хардфорк;
get_potential_signatures — возвращает потенциальные публичные ключи для подписи транзакции;
get_recovery_request — возвращает данные по запросу на восстановление доступа к аккаунту;
get_required_signatures — возвращает публичные ключи из предложенных, которые необходимы для подписи транзакции (нужно направить транзакцию без подписи и предоставить открытые ключи);
get_transaction_hex — возвращает hex значение сырой транзакции;
get_vesting_delegations — возвращает список делегированной доли аккаунта;
get_withdraw_routes — возвращает массив путей понижения доли для аккаунта;
lookup_account_names — возвращает массив аккаунтов по запрошенным логинам;
lookup_accounts — возвращает массив логинов аккаунтов по нижней границе с указанием количества возвращаемых элементов (не более 1000);
get_witness_by_account — возвращает делегата в соответствием с его логином;
get_witness_count — возвращает количество аккаунтов, заявивших о желании быть делегатом;
get_witness_schedule — возвращает очередь делегатов дополненную расчитанными медианными значениями параметров сети и мажориторной версией хардфорка;
get_witnesses — возвращает массив делегатов в соответствием с их id (можно запросить нескольких в массиве);
get_witnesses_by_vote — возвращает массив делегатов, отсортированных по потенциалу полученных голосов (указывается левая граница списка и количество возвращаемых значений в массиве, но не более 100);
lookup_witness_accounts — возвращает массив логинов аккаунтов, которые заявляли себя как делегаты (указывается левая граница списка и количество возвращаемых значений в массиве, но не более 1000).