HF18: Изменения в API
В версии HF•18 реализованы новые функциональные и технические возможности, предоставляющие пользователям более удобное взаимодействие с системой, повышенную защиту от злоупотребления голосованием, а также повышающие быстродействие системы за счет более оптимального перераспределения методов между плагинами API.
- Б локирование различного вида злоупотреблений делегированием Силы Голоса.
- Обеспечение более гибкой ценовой политики на бирже за счет удаления старых данных и использования актуальных в определении курса и соотношения крипто-валют.
- Возможность пользователям вносить изменения в профиль с использованием ключа posting.
- Возможность пользователям предлагать транзакцию на подписание, состоящей из нескольких операций.
- Возможность пользователям вносить изменения в посты и комментарии независимо от срока их публикации и придавать им актуальность.
- Повышение быстродействия системы за счет размещения в разных объектах полей с часто и редко используемыми данными.
- Повышение производительности API протокола за счет удаления неиспользуемых полей из методов плагинов, а также за счет перераспределения методов между плагинами для более эффективного их использования.
- Применение фильтрации тегов для настройки ленты в более удобной для пользователя форме.
- Возможность постраничного вывода личных сообщений на экран пользователя.
В данный плагин добавлена возможность постраничного вывода списка личных сообщений. Изменены следующие методы (шрифтом bold выделены добавленные аргументы):
- get_inbox(string to, time_point newest , uint limit, uint offset)
- get_outbox(string from, time_point newest , uint limit, uint offset)
Метод
get_inbox
возвращает список входящих сообщений начиная с даты, заданной в newest.
Метод get_outbox
возвращает список исходящих сообщений начиная с даты, заданной в newest.
limit
— ограничивает количество сообщений (максимально допустимое значение — 100).
offset
— номер сообщения, с которого выполняется операция (начиная с №).Плагин
witness_api
образован перемещением части методов с часто используемыми полями из плагина database_api
. В него вошли следующие методы:- get_current_median_history_price
- get_feed_history
- get_miner_queue
- get_witness_schedule
- get_witnesses
- get_witness_by_account
- get_witnesses_by_vote
- get_witness_count
- lookup_witness_accounts
- get_active_witnesses // <- из выдаваемого результата удалены пустые строки
Все методы перемещены
в witness_api
без изменений во входных параметрах и выдаваемых результатах. Исключение составляет метод get_active_witnesses
, у которого из выдаваемого результата удалены пустые строки.Плагин
account_history
дополнен следующим методом:- get_account_history
Метод перемещен из
database_api
без изменений во входных параметрах и выдаваемых результатах.Плагин
operation_history
образован перемещением методов из плагина database_api
. Создание данного плагина позволяет отделить индексирование о пераций в блокчейне от истории пользователей. Пользователь может запрашивать и получать информацию об операциях в транзакциях (блоках) без ведения истории по аккаунтам. Это обеспечивает снижение нагрузки на сервер и на потребляемую память.Плагин
operation_history
дополнен следующими методами:- get_ops_in_block
- get_transaction
Методы перемещены из
database_api
без изменений во входных параметрах и выдаваемых результатах.Часть методов из плагина
social_network
была перемещена во вновь созданный плагин tags
. Перенос методов осуществлен для того, чтобы создание дополнительных индексов и поиск информации по ним проводились в отдельном плагине. В плагине social_network
оставлены методы, обеспечивающие обращение к корневым элементам, а методы, обрабатывающие теги, перемещены в новый плагин tags
.Введен опциональный параметр
vote_limit
для задания максимального количества проголосовавших в ответе пользователю. По умолчанию его значение принимается равным 10000. Например, количество комментариев к посту может достигать 1000 и более, что затрудняет их просмотр и поиск интересующей информации. Пользователь может с использованием тэга сформировать запрос на получение комментариев, выбранных (отсортированных) в соответствии с указанными в тэге признаками. Параметр vote_limit
позволяет уменьшить размер отправляемого от сервера ответа. При этом в ответе добавляется дополнительное поле active_votes_count
, информирующее об общем количестве проголосовавших (без необходимости получать полный список).Изменена результирующая структура:
struct discussion {
"active_votes_count": uint, // <— Добавлено. Общее количество голосов для vote_limit
...
}
Изменения внесены в методы, возвращающие структуру
discussion
и массив discussion
. В этот перечень вошли следующие методы:- get_replies_by_last_update(string start_parent_author, string start_permlink, uint limit
[, uint vote_limit]
) - get_content(string account, string permlink
[, uint vote_limit]
) - get_content_replies(string author, string permlink
[, uint vote_limit]
) - get_all_content_replies(string author, string permlink
[, uint vote_limit]
) - get_content(string author, string permlink
[, uint32_t limit]
) - get_active_votes(string account, string permlink
[, uint vote_limit]
) - get_account_votes(string account
[, uint from, uint vote_limit]
)
Фоном выделены параметры, которыми были дополнены методы.
Следующие методы, дублирующие функции плагина
tag
, были удалены из плагина social_network
:- get_trending_categories
- get_active_categories
- get_recent_categories
- get_best_categories
В плагин
tags
перемещены методы, выполняющие операции с тэгами (например, получение наиболее популярных тэгов; получение списка языков; получение тэгов, используемых автором). Это позволяет сэкономить размер файла разделяемой памяти тем пользователям, которые не используют данную функциональность.Методы, которые перемещены из
social_network
без изменений:- get_trending_tags(string start, uint limit)
- get_languages()
- get_tags_used_by_author(string)
- get_discussions_by_payout(query)
- get_discussions_by_trending(query)
- get_discussions_by_created(query)
- get_discussions_by_active(query)
- get_discussions_by_cashout(query)
- get_discussions_by_votes(query)
- get_discussions_by_children(query)
- get_discussions_by_hot(query)
- get_discussions_by_feed(query)
- get_discussions_by_blog(query)
- get_discussions_by_comments(query)
- get_discussions_by_promoted(query)
В метод
get_discussions_by_author_before_date
добавлен новый параметр vote_limit
(шрифтом bold выделен добавленный параметр):- get_discussions_by_author_before_date(string author, string start_permlink, datetime before_date, uint limit [, uint vote_limit])struct discussion_query {limit: uint,select_tags: [string],filter_tags: [string]select_languages: [string],filter_languages : [string],truncate_body: uint,vote_limit: uint, // <— Новый параметр, по умолчанию принимает значение 10000select_authors : [string],start_author: string,start_permlink: string,parent_author: string,parent_permlink: string}Изменена результирующая структура метода:struct discussion {“reputation”: uint, // <- Поле отсутствует, если выключен плагин follow"active_votes_count": uint, // <- Добавлено. Общее количество голосов для vote_limit...}
В плаг ине
follow
изменена структура метода get_account_reputations
в соответствии со следующим представлением:- get_account_reputations(array accounts)
- Результат array
Плагин
database_api
дополнен новыми методами для выполнения новых операций.Новые методы:
Новые операции:
Часть методов из
database_api
перемещена в плагины witness_api
, account_history
, operationt_history
и follow
. Сохраненными в database_api
без изменений остались следующие методы:- get_block_header
- get_block
- set_block_applied_callback
- get_config
- get_dynamic_global_properties
- get_chain_properties
- get_hardfork_version
- get_next_scheduled_hardfork
- get_account_count
- get_owner_history
- get_recovery_request
- get_escrow
- get_withdraw_routes
- get_account_bandwidth
- get_savings_withdraw_from
- get_savings_withdraw_to
- get_conversion_requests
- get_transaction_hex
- get_required_signatures
- get_potential_signatures
- verify_authority
- verify_account_authority
- lookup_account_names
- lookup_accounts
Поля
average_bandwidth
и average_market_bandwidth
были удалены из плагина database_api
как неиспользуемые. Заменяемые их в выполнении операций поля new_average_bandwidth
, new_average_market_bandwidth
были переименованы в первоначальные их имена average_bandwidth
и average_market_bandwidth
соответственно.Поле
lifetime_bandwidth
было удалено и заменено на вновь созданное одноименное поле lifetime_bandwidth
, зависящее от новых значений, а также поле lifetime_market_bandwidth
для использования в маркетинговых операциях.Из описания типа
bandwidth_type
, используемого в вызове метода get_account_bandwidth
, удалены поля old_forum
и old_market
.В поле
lifetime_bandwidth
хранится суммарное значение bandwidth
, используемое аккаунтом за все время его работы. В поле average_bandwidth
хранится среднее значение bandwidth
, по которому определяется порог чрезмерной активности аккаунта.- get_accountsstruct account {reputation, // <- Поле отсутствует, если выключен плагин followtransfer_history, // <- Удаленоmarket_history, // <- Удаленоpost_history, // <- Удаленоvote_history, // <- Удаленоother_history, // <- Удаленоtags_usage, // <- Удаленоguest_bloggers, // <- Удаленоblog_category, // <- Удалено...}Удаление полей из структуры account обусловлено тем, что ранее эти поля никогда не использовались.
Этот метод обрабатывает запрос на выдачу списка предложенных для подписания транзакций, поступивший от какого-либо аккаунта. Метод возвращает массив транзакций, в который входят транзакции, созданные непосредственно данным аккаунтом, а также транзакции, которые ему необходимо подписать.
- get_proposed_transaction(account: string)struct proposal_object {author: string,title: string,memo: string,expiration_time: datetime,review_period_time: datetime, // может отсутствоватьproposed_operations: [ operation ],required_active_approvals: [ string ],available_active_approvals: [ string ],required_owner_approvals: [ string ],available_owner_approvals: [ string ],required_posting_approvals: [ string ],available_posting_approvals: [ string ],available_key_approvals: [ string ]};
Этот метод возвращает информацию о текущем статусе разделяемой памяти, в том числе: общий объем разделяемой памяти, размер свободного и зарезервированного пространства для определенных нужд, а также список индексов, хранящихся в разделяемой памяти (название индекса, количество записей).
- get_database_info()struct database_info {total_size: uint,free_size: uint,reserved_size: uint,used_size: uintindex_list: [{name: string,record_count: uint},]};
Этот метод возвращает массив значений с описанием операции делегирования (далее — блок делегирования) аккаунта (делегированный другим аккаунтам или же полученный от других аккаунтов).
- get_vesting_delegationsget_vesting_delegations(string account,string from, uint32_t limit = 100,delegations type = delegated)
account
— аккаунт, по запросу от которого выдается блок делегирования. Отправитель*/получатель определяется аргументомtype
.from
— начальный аккаунт, парный в операции делегирования. Получатель/отправитель - задается аргументомtype
(для пагинации).limit
— количество возвращаемых элементов (для пагинации). По умолчанию принимается равным 100. Максимальное значение равно 1000.type
— тип запрашиваемого блока делегирования: "delegated" (делегированный), "received" (полученный). По умолчанию принимает значение "delegated".
Пример возвращаемого блока делегирования:
массив vesting_delegation_api_object [{id: 0, delegator: "zzz", delegatee: "zxcat", vesting_shares: "90.000000 GESTS", min_delegation_time: "2018-04-25T21:48:15"}]
.Этот метод используется для получения списка возвращаемых (отозванных и «замороженных») делегированных средств аккаунт а. Метод возвращает результат в виде массива значений с описанием операции возврата делегированных средств (далее — блок отозванного делегирования)
- get_expiring_vesting_delegationsget_expiring_vesting_delegations(string account,time_point_sec from,uint32_t limit = 100)
account
— аккаунт, возвращающий делегированные средства.from
— начальное время возврата делегированных средств (для пагинации).limit
— количество возвращаемых элементов (для пагинации). По умолчанию принимается равным 100. Максимальное значение равно 1000.
Пример возвращаемого модулем блока отозванного делегирования:
массив vesting_delegation_expiration_api_object, [{id: 0, delegator: "zxcat", vesting_shares: "123.000000 GESTS", expiration: "2018-05-25T11:18:45"}]
.Эта операция позволяет изменять количество делегированного, а также осуществлять возврат делегированного в полном объеме. Для выполнения этих операций необходима подпись ключом
active
. Операции выполняются с использованием следующей процедуры:delegate_vesting_shares
{
delegator: string, // делегирующий аккаунт
delegatee: string, // аккаунт-получатель
vesting_shares: asset // новое количество делегируемой Силы Голоса
}
Для выполнения этой опирации требуется подпись ключом
active
.Для изменения количества делегирования Силы Голоса в поле
vesting_shares
следует задать новое значение. Для полного возврата делегированной части Силы Голоса в поле vesting_shares
следует задать значение вида “0.000000 GESTS”. При изменении значения в сторону уменьшения делегированная Сила Голоса сразу снимется с аккаунта-получателя и переходит в «замороженное» состояние сроком на семь дней (в случае создания аккаунта с делегированием этот период определяется параметром create_account_delegation_time
).Минимальное количество Силы Голоса, необходимое для делегирования, определяется по результатам голосования делегатов.
Операция выполняется с использованием следующей процедуры:
account_create_with_delegation
{
fee: asset, // комиссия, в GOLOS
delegation: asset, // делегируемая доля, в GESTS
creator: string,
new_account_name: string,
owner: authority,
active: authority,
posting, authority,
memo_key: string,
json_metadata: string,
extensions: extensions_type // Не используется, исходное значение — пусто
}
Для выполнения этой опирации требуется подпись ключом
active
.Для создания аккаунта с делегированием необходимо, чтобы выполнялись следующие два условия:
1. fee ≥ create_account_min_golos_fee
2. (delegation) ≥ (create_account_min_delegation)
где
fee
— размер комиссионных отчислений;
create_account_min_golos_fee
— минимальный размер комиссионных отчислений в криптовалюте Голос, требуемых на создание аккаунта с делегированием;
delegation
— делегированная часть Силы Голоса;
create_account_min_delegation
— минимальное количество Силы Голоса, необходимое для создания аккаунта с делегированием.При создании аккаунта с делегированием бо́льшую часть комиссии можно оплатить с «заморозкой» на период, определяемый параметром
create_account_delegation_time
. Делегированная Сила Голоса может быть отозвана в любой момент (например, в случае злоупотребления полученной делегированной частью новым аккаунтом). При этом делегированная Сила Голоса будет снята с нового аккаунта сразу, а на делегирующий аккаунт будет возвращена по истечении срока «заморозки». Время «заморозки» является параметром, определяемым по результатам голосования. Его значение выбирается по медиане из списка всех значений, полученных от делегатов с помощью операции chain_properties_update_operation
.Пользователю предоставляется возможность изменять метаданные своего профиля без использования ключа
active
. Поля профиля хранятся в json_metadata
. Для изменения любого поля профиля требовалась подпись только ключом active
, что не всегда было приемлемым.Было принято решение разделить поля на две группы. В состав первой группы вошли поля с наиболее значимыми данными профиля (ключи:
posting
, active
, owner
и memo
), а в другую — с менее значимыми, но часто использу емыми (аватар, пол, местонахождение и пр.). Процедура изменения полей первой группы сохранена и требует подписи только ключом active
. В версии HF•18 вносить изменения в поля второй группы стало возможным с использованием ключа posting
для подписи.