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_accounts
struct 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_delegations
get_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_delegations
get_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, // комиссия, в GOLOSdelegation: asset, // делегируемая доля, в GESTScreator: 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_fee2. (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 для подписи.
Операция выполняется с использованием следующей процедуры:
account_metadata{account: string, // изменяемый аккаунтjson_metadata: string // новое значение json_metadata}
Для выполнения этой опирации требуется подпись ключом posting.
Пользователю предоставляется возможность предлагать транзакцию на блокчейне с несколькими отдельными операциями, требующих одобрения от пользователей на их выполнение.
Операция выполняется с использованием следующей процедуры:
proposal_create_operation{author: string, // автор предлагаемой транзакцииtitle: string, // заголовок предложенной транзакции.memo: string, // примечаниеproposed_operations: [ operation ], // список операций в предлагаемой транзакцииexpiration_time: datetime, // максимальное время, отведенное на транзакциюreview_period_time: datetime, // время на принятие решения участников транзакции. Опциональный параметрextensions: extensions_type // расширение, по аналогии с другими операциями. Исходное значение — пусто}
Для выполнения этой опирации требуется подпись ключом active.
Создаваемая транзакция должна быть уникальной по сочетанию полей author-title. По этой паре author-title идентифицируется транзакция в случае внесения в нее изменений или ее удаления.
В поле proposed_operations задается список операций для выполнения их в транзакции (например, {["delete_comment_operation":{"autor":"jim", "permlink":"hello"}}]). На каждую операцию из этого списка должна быть получена подпись автора, которому она предназначена. Право проставления подписи на выполнение любой операции из списка имеет также каждый из участников транзакции. Например, операция публикации поста назначается одному автору, а операция перечисления вознаграждения за нее — другому. В случае несогласия другого автора с выполнением второй операции он может удалить подпись на выполнение первой операции предложенной транзакции.
В поле review_period_time проставляется время, отводимое на принятие решений участников транзакции. Этот период должен быть меньше максимального времени из поля expiration_time, которое отводится на транзакцию. По истечении этого периода подписи в транзакции могут быть только удаляться.
Если параметр review_period_time не задан, то транзакция будет сразу выполняться после сбора всех необходимых подписей.
Автору, а также участникам транзакции, предоставляется возможность менять свое решение и обновлять подписи до истечения времени, отводимого на транзакцию.
Если транзакция не получает одобрения на выполнение какой-либо из операций, эта транзакция не отменяется и ее актуальность будет сохраняться до отведенного на ее выполнение времени. После получения всех необходимых подписей транзакция сразу будет выполняться и все последующие обновления будут считаться недействительными.
Операция выполняется с использованием следующей процедуры:
proposal_update_operation{author: string, // автор предложенной транзакцииtitle: string, // заголовок предложенной транзакции.active_approvals_to_add: [string], // список аккаунтов для подписи. Транзакция должна быть// подписана ключом activeactive_approvals_to_remove: [string], // список аккаунтов для удаления подписи из предложенной// транзакции. Транзакция должна быть подписана ключом activeowner_approvals_to_add: [string], // список аккаунтов для подписи на операции в предложенной// транзакции. Транзакция должна быть подписана ключом ownerowner_approvals_to_remove: [string], // список аккаунтов для удаления подписи из предложенной//транзакции. Транзакция должна быть подписана ключом ownerposting_approvals_to_add: [string], // список аккаунтов для подписи на операции в предложенной// транзакции. Транзакция должна быть подписана ключом postingposting_approvals_to_remove: [string], // список аккаунтов для удаления подписи из предложенной// транзакцию. Транзакция должна быть подписана ключом postingkey_approvals_to_add: [string], // список ключей public для проставления подписей в предложенной// транзакцииkey_approvals_to_remove: [string], // список ключей public для удаления подписей из предложенной// транзакцииextensions: extensions_type // расширение, по аналогии с другими операциями. Исходное значение — пусто}
Подпись зависит от списка операций, предлагаемых на подписание.
По этой паре author-title идентифицируется транзакция в случае внесения в нее изменений или ее удаления. Поля, в которые записывается псевдоним для подписи транзакции, выбираются в зависимости от типа операций в предложенной транзакции.
В случае отказа кого-либо из участников транзакции в выполнении операции он может сформировать запрос на удаление предложенной транзакции. Идентификация транзакции осуществляется по паре author-title.
Операция выполняется с использованием следующей процедуры:
proposal_delete_operation{author: string, // автор предложенной транзакцииtitle: string, // заголовок предложенной транзакцииrequester: string, // псевдоним запросившего удаление транзакции или автор предложенной транзакцииextensions: extensions_type // расширение, по аналогии с другими операциями. Исходное значение — пусто}
Для выполнения этой опирации требуется подпись ключом active.
Удалить предложенную транзакцию может как ее автор, так и любой участник, от которого требуется подпись. Если хотя бы один из участников запрашивает удаление транзакции, то, независимо от подписей остальных участников, данная транзакция будет удалена.
Предыдущие версии блокчейна обеспечивают поддержку операции witness_update, которая позволяет делегатам Голоса изменять по результатам голосования значения следующих параметров:
account_creation_fee— размер комиссионных отчислений, требуемых на создание аккаунта без делегирования;maximum_block_size— максимальный размер блока блокчейна;sbd_interest_rate— процент, начисляемый на SBD.
Ввиду того, что witness_update не позволяет расширить перечень параметров, значения которых определяются голосованием, в версии HF•18 реализована новая операция chain_properties_update, которая поддерживает более расширенный перечень таких параметров и позволяет наращивать его в будущем. В версии HF•18 операция chain_properties_update поддерживает следующий перечень параметров, значения которых определяются голосованием:
account_creation_fee— размер комиссионных отчислений, требуемых на создание аккаунта без делегирования;maximum_block_size— максимальный размер блока блокчейна;sbd_interest_rate— процент, начисляемый на SBD;create_account_min_golos_fee— минимальный размер комиссионных отчислений в криптовалюте Голос, требуемых на создание аккаунта с делегированием (по умолчанию принимает значение "1.000 GOLOS", см. операцию account_create_with_delegation);create_account_min_delegation— устанавливает минимально возможное количество Силы Голоса при создании аккаунта с делегированием (по умолчанию принимает значение "5.000 GOLOS", см. операцию account_create_with_delegation);create_account_delegation_time— устанавливает минимально возможное время (в секундах) «заморозки» делегированной Силы Голоса при создании аккаунта с делегированием (по умолчанию принимает значение за период в 30 дней, см. операцию account_create_with_delegation);min_delegation— устанавливает минимально возможное количество Силы Голоса для делегирования на аккаунт (по умолчанию принимает значение "10.000 GOLOS", см. операцию delegate_vesting_shares).
Операция выполняется с использованием следующей процедуры:
chain_properties_update_operation{owner: string, // автор измененияprops: {account_creation_fee: asset,maximum_block_size: uint,sbd_interest_rate: uint,create_account_min_golos_fee: uint,create_account_min_delegation: uint,create_account_delegation_time: uint,min_delegation: uint}}
Для выполнения этой опирации требуется подпись ключом active.
