SF18.4: Новые функции

Дополнительная информация в оповещениях о подписанных блоках

Получение информации о виртуальных операциях в блоке

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

В версии SF-0.18.4 в вызов метода set_block_applied_callback() добавлен настраиваемый параметр type, принимающий четыре значения. В зависимости от задаваемого значения этого параметра, пользователь может получать следующую информацию о блоке: — подписанный блок; — заголовок блока; — виртуальные операции блока; — подписанный блок и виртуальные операции.

Пользователь имеет возможность получать не только наиболее полную информацию о подписанном блоке, но также задавать ее содержимое по своему усмотрению.

Соответствие задаваемого значения параметра и типа получаемой информации приведено в следующей таблице.

Значение параметра	Альтернативное значение параметра	Тип информации в оповещении
«block»	0	Подписанный блок (по аналогии с версией HF 18.0)
«header»	1	Заголовок блока (по аналогии с версией HF 16.4)
«virtual_ops»	2	Только виртуальные операции блока
«full»	3	Подписанный блок и виртуальные операции блока

Любое другое задаваемое значение параметра принимается методом set_block_applied_callback() как «block».

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

void set_block_applied_callback(
    block_applied_callback_result_type type
)

Параметр: type — тип информации в получаемом оповещении.

Получение информации о транзакциях на Узле, не включенных в блок

В версии SF-0.18.4 введен дополнительный (ранее разработанный, но заблокированный для использования) вид операции оповещения пользователя о блоках. Данная операция выполняет отправку сообщения пользователю о появившихся на Узле блокчейна транзакциях, уже подписанных, но еще не включенных в блок. Информация о таких транзакциях отсутствует в блоках и поэтому не может быть доступна пользователю с помощью обычного вызова set_block_applied_callback().

Пользователю для подписания на получение оповещения о таких транзакциях необходимо вызвать API-метод set_pending_transaction_callback().

Получение информации о вознаграждении подписчика блока

В версии SF-0.18.4 введена новая виртуальная (не заданная явным образом) операция producer_reward_operation(), генерируемая на каждом из блоков. Операция оповещает пользователя о вознаграждении в виде GESTS подписчика блока — продюсера блока, которым может являться одно из следующих лиц: — делегат, входящий в утвержденный список делегатов; — делегат, выбранный случайным образом; — майнер.

Виртуальная операция имеет вид:

struct producer_reward_operation {
    account_name_type producer;
    asset vesting_shares
};

Параметры: producer — имя аккаунта-продюсера блока; vesting_shares — размер вознаграждения (в GESTS).

Виртуальная операция хранится в истории Узла блокчейна и может быть запрошена API-методом get_ops_in_block() для получения информации о вознаграждении продюсера блока. Метод имеет вид:

std::vector<applied_operation> get_ops_in_block(
    uint32_t block_num,
    bool only_virtual
)

Параметры: block_num — идентификатор блока, виртуальные операции которого запрашиваются; only_virtual — «true», если возвращаются только виртуальные операции.

Улучшение диагностики ошибок

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

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

Был проведен анализ ошибок непосредственно в местах их формирования с последующей их классификацией по информативным признакам. В результате анализа было выделено три класса ошибок: 1. ошибки пользователя в задании параметров; 2. ошибки пользователя при выполнении операций бизнес-логики (например, превышение bandwidth; 3. ошибки в тексте программы (внутренние ошибки блокчейна, не зависящие от пользователя).

Каждый из этих классов ошибок был разбит на подклассы и далее на категории ошибок. Были получены следующие категории ошибок: 1. неподдерживаемая блокчейном операция; 2. ошибка количества аргументов, переданных плагину; 3. ошибка значения параметра (проверка синтаксиса заданного значения параметра, в том числе: наличие недопустимых символов в именах аккаунтов, корректность записи единиц актива, превышение максимально допустимого количества символов в комментарии); 4. превышение лимита на выдачу результата операции; 5. ошибка структуры запроса JSON-API (например, наличие незаполненного поля, запрос к несуществующему методу); 6. нарушение структуры транзакции; 7. отсутствие заданного объекта (например, отсутствие аккаунта с заданным именем или транзакции с заданным идентификатором); 8. отсутствие требуемой версии HardFork; 9. ошибка бизнес-логики (например, попытка клиента подписать на себя бизнес-объект), в том числе: — отсутствие достаточного количества активов для выполнения операции; — превышение значения bandwidth (например, превышение количества размещаемых постов или отдаваемых голосов за определенный период); 10. ошибка сервера (например, отсутствие доступа к серверу); 11. выполнение операции на заблокированном кошельке; 12. ошибка программного кода , в том числе: — ошибка, возникающая в используемых библиотеках; — ошибка кода (например, недопустимое использование функции внутри кода).

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

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

Создание многофункционального плагина для обработки личных сообщений пользователя

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

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

Операции с личными сообщениями пользователя

Отправка, редактирование личных сообщений

Для отправки и редактирования сообщений пользователя используется следующий метод:

struct private_message_operation {
    account_name_type from;  
    account_name_type to;  
    uint64_t nonce;   
    public_key_type from_memo_key;   
    public_key_type to_memo_key;  
    uint32_t checksum;  
    bool update;  
    vector<char> encrypted_message
};

Параметры: from — имя аккаунта, отправляющего сообщение; to — имя аккаунта, которому адресовано сообщение; nonce — произвольное целочисленное значение, уникальное значение части ключа (рекомендуется использовать текущее время в миллисекундах); from_memo_key — публичный ключ категории memo отправителя, используемого для шифрования сообщения; to_memo_key — публичный ключ категории memo получателя сообщения, используемого для расшифровки сообщения; checksum — контрольная сумма результата ключа шифрования; update — “true”, если сообщение редактируется (поля from, to, nonce); “false”, если сообщение создается; encrypted_message — результирующее сообщение.

Для редактирования сообщения требуется указывать уникальный ключ (поля from, to, nonce). Алгоритм получения ключа шифрования аналогичен алгоритму шифрования поля memo в операциях с переводами средств.

Внутри зашифрованного сообщений содержится структура в формате JSON, которая может быть расширена. Структура имеет вид:

struct  message {  
    string  subject;  
    string body  
};

Удаление личного сообщения

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

struct private_delete_message_operation {
    account_name_type requester;  
    account_name_type from;  
    account_name_type to;  
    uint64_t nonce;  
    time_point_sec start_date;  
    time_point_sec stop_date  
};

Параметры: requester — имя аккаунта, запросившего опреацию удаления; from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; nonce — уникальное значение части ключа (поля from, to, nonce); start_date — дата и время, начиная от которого сообщения должны быть удалены; stop_date — дата и время, заканчиваясь которым сообщения должны быть удалены.

Для удаления сообщения требуется указать уникальный ключ (поля from, to, nonce). Для удаления серии сообщений дополнительно требуется указать диапазон сообщений start_date-stop_date.

Пометка личных сообщений как прочитанных

Сообщение (или группа сообщений) может быть помечена меткой вида «прочитанное». Операция выполняется аналогично операции удаления сообщений и вызывается следующим методом:

struct private_mark_message_operation {
    account_name_type from;
    account_name_type to;
    uint64_t nonce;
    time_point_sec start_date;
    time_point_sec stop_date
};

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; nonce — уникальное значение части ключа (поля from, to, nonce); start_date — дата и время, начиная от которого сообщения должны быть помечены как прочитанные; stop_date — дата и время, заканчиваясь которым сообщения должны быть помечены как прочитанные.

Для пометки сообщения требуется указать уникальный ключ (поля from, to, nonce). Для пометки серии сообщений дополнительно требуется указать диапазон сообщений start_date-stop_date.

Создание и настройка контакт-листа аккаунтов

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

Пользователь может добавлять в контакт-лист нового аккаунта, с которым еще не обменивался сообщением. Метод, выполняющий создание нового контакта, имеет следующий вид:

struct private_contact_operation {
    account_name_type owner;
    account_name_type contact;
    private_contact_type type;
    string json_metadata
};

Параметры: owner — имя аккаунта, создающего контакт; contact — имя аккаунта, добавляемого в контакт-лист; type — тип контакта (pinned, чтобы добавить контакт); json_metadata — данные о добавляемом в контакт-лист аккаунте в формате JSON.

Разрешенные типы контактов:

enum private_contact_type {
    unknown = 1, // неизвестный контакт
    pinned = 2,    // контакт, который персонально добавляется контакт лист
    ignored = 3  // игнорируемый контакт 
};

Для удаления контакта из контакт-списка, необходимо задать тип unknown и удалить все его сообщения. Для внесения аккаунта в контакт-лист необходимо задать тип pinned. Для прекращения приема сообщений от контакта из контакт-списка, необходимо задать тип ignored. Для прекращения приема сообщений от всех аккаунтов, за исключением находящихся в контакт-листе, необходимо настроить контакт-лист. Операция по настройке контакт-листа выполняется вызовом следующего метода:

struct private_settings_operation {
    account_name_type owner;
    bool ignore_messages_from_unknown_contact
};

Параметры: owner — имя аккаунта, собственника контакт-листа; ignore_messages_from_unknown_contact — "true" для прекращения получения сообщений от неизвестного контакта.

Операции с личными сообщениями пользователя с использованием клиентского приложения cli_wallet

Отправка личного сообщения

Отправление личного сообщения аккаунту выполняется вызовом следующего метода:

send_private_message(
    string from, 
    string to, 
    message_body message,
    bool broadcast
);

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; message — сообщение вида ({"subject":"", "body":""}) broadcast — “true”, если операция пересылается на сервер; “false”, если транзакция выводится на экран.

Редактирование личного сообщения

Редактирование личного сообщения выполняется следующим методом:

edit_private_message(
    string from, 
    string to, 
    uint64_t nonce, 
    message_body message, 
    bool broadcast
);

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; nonce — уникальное значение части ключа (поля from, to, nonce); message — сообщение вида ({"subject":"", "body":""}); broadcast — “true”, если операция пересылается на сервер; “false”, если транзакция выводится на экран.

Получение списка входящих сообщений

Для получения списка входящих сообщений используется следующий метод:

get_private_inbox(
    string to, 
    message_box_query query
);

Параметры: to — имя аккаунта-получателя сообщения; query — параметры поиска.

Получение списка отправленных сообщений

Для получения списка отправленных сообщений используется следующий метод:

get_private_outbox(
    string from, 
    message_box_query query
);

Параметры: from — имя аккаунта-отправителя сообщения; query — параметры поиска.

Получение списка из канала сообщений

Для получения списка из канала сообщений используется следующий метод:

get_private_thread(
    string from, 
    string to, 
    message_thread_query query
);

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; query — параметры поиска.

Настройка личных сообщений

Для настройки личных сообщений используется следующий метод:

set_private_settings(
    string owner, 
    settings_api_object settings, 
    bool broadcast
);

Параметры: owner — имя аккаунта, собственника контакт-листа; settings — настройки; broadcast — “true”, если операция пересылается на сервер. “false”, если транзакция выводится на экран.

Получение настроек личных сообщений

Для получения настроек личных сообщений используется следующий метод:

get_private_settings(string owner)

Параметр: owner — имя аккаунта, собственника контакт-листа.

Добавление и изменение контакта личных сообщений в контакт-листе

Для добавления или изменения контакта в контакт-листе используется следующий метод:

add_private_contact(
    string owner, 
    string contact, 
    private_contact_type type, 
    string json_metadata, 
    bool broadcast
)

Параметры: owner — имя аккаунта, собственника контакт-листа; contact — имя аккаунта, контакт которого добавляется или изменяется в контакт-листе; type — тип контакта (unknown - неопределенный, pinned - закрепленный, ignored - игнорируемый); json_metadata — данные контакта в формате JSON; broadcast — "true", если операция пересылается на сервер; "false", если транзакция выводится на экран.

Получение списка контактов личных сообщений из контакт-листа

Для выполнения данной операции необходимо задать тип контактов, по которому будет сформирован требуемый список контактов, имеющихся в в контакт-листе. Операция выполняется с использованием следующего метода:

get_private_contacts(
    string owner, 
    private_contact_type type, 
    int limit, 
    int offset
);

Параметры: owner — имя аккаунта, собственника контакт-листа; type — тип контактов, по которому формируется список; limit — максимальное количество контактов в формируемом списке; offset — смещение относительно начала контактов в контакт-листе, от которого формируется список.

Получение информации об отдельном контакте

Для получения информации об отдельном контакте из контакт-листа используется следующий метод:

get_private_contact(
    string owner, 
    string contact
);

Параметры: owner — имя аккаунта, собственника контакт-листа; contact — имя аккаунта контакта.

Удаление личного сообщения из списка входящих

Для удаления личных сообщений из списка входящих используется следующий метод:

delete_inbox_private_message(
    string from, 
    string to, 
    uint64_t nonce, 
    bool broadcast
);

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; nonce — уникальное значение части ключа (поля from, to, nonce); broadcast — “true”, если операция пересылается на сервер; “false”, если транзакция выводится на экран.

Удаление серии сообщений из списка входящих

Для удаления серии личных сообщений из списка входящих используется следующий метод:

delete_inbox_private_messages(
    string from, 
    string to, 
    time_point_sec start_date, 
    time_point_sec stop_date, 
    bool broadcast
);

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; start_date — дата и время, начиная от которого входящие сообщения должны быть удалены; stop_date — дата и время, заканчиваясь которым входящие сообщения должны быть удалены; broadcast — “true”, если операция пересылается на сервер; “false”, если транзакция выводится на экран.

Удаление сообщения из списка отправленных

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

delete_inbox_private_message(
    string from, 
    string to, 
    uint64_t nonce, 
    bool broadcast
);

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; nonce — уникальное значение части ключа (поля from, to, nonce); broadcast — “true”, если операция пересылается на сервер; “false”, если транзакция выводится на экран.

Удаление серии сообщений из списка отправленных

Для удаления серии личных сообщений из списка отправленных используется следующий метод:

delete_outbox_private_messages(
    string from, 
    string to, 
    time_point_sec start_date, 
    time_point_sec stop_date, 
    bool broadcast
);

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; start_date — дата и время, начиная от которого отправленные сообщения должны быть удалены; stop_date — дата и время, заканчиваясь которым отправленные сообщения должны быть удалены; broadcast — “true”, если операция пересылается на сервер; “false”, если транзакция выводится на экран.

Пометка личного сообщения как прочитанного

Операция выполняется аналогично операции удаления сообщения и вызывается следующим методом:

mark_private_message(
    string from, 
    string to, 
    const uint64_t nonce, 
    bool broadcast
);

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; nonce — уникальное значение части ключа (поля from, to, nonce); broadcast — “true”, если операция пересылается на сервер; “false”, если транзакция выводится на экран.

Пометка серии личных сообщений как прочитанных

Операция выполняется аналогично операции удаления сообщений и вызывается следующим методом:

mark_private_messages(
    string from, 
    string to, 
    time_point_sec start_date,
    time_point_sec stop_date, 
    bool broadcast
);

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; start_date — дата и время, начиная от которого сообщения должны быть помечены как прочитанные; stop_date — дата и время, заканчиваясь которым сообщения должны быть помечены как прочитанные; broadcast — “true”, если операция пересылается на сервер; “false”, если транзакция выводится на экран.

API личных сообщений пользователя

Получение списка личных сообщений

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

struct message_api_object {
    account_name_type from;  
    account_name_type to;  
    uint64_t nonce;  
    public_key_type from_memo_key;  
    public_key_type to_memo_key;  
    uint32_t checksum;  
    std::vector<char> encrypted_message;  
    time_point_sec create_date;  
    time_point_sec receive_date;  
    time_point_sec read_date;  
    time_point_sec remove_date  
};

Параметры: from — имя аккаунта-отправителя сообщения; to — имя аккаунта-получателя сообщения; nonce — случайное число, необходимое для дешифрования сообщения и являющееся составной частью уникального ключа (с содержанием полей from, to и nonce); from_memo_key — публичная часть ключа memo аккаунта-отправителя; to_memo_key — публичная часть ключа memo аккаунта-получателя; checksum — контрольная сумма ключа шифрования; encrypted_message — зашифрованное сообщение; create_date — дата и время создания сообщения; receive_date — дата и время получения сообщения. Если сообщение не редактируется, значение этого поля совпадает со значением поля create_data; read_date — дата и время прочтения сообщения; remove_date — дата и время удаления сообщения из ящика аккаунта собеседника.

Просмотр сообщений, получаемых из ящиков входящих и исходящих сообщений

Для просмотра сообщений, хранящихся в ящиках входящих и исходящих сообщений, используется структура следующего вида:

struct message_box_query {
    set<string> select_accounts;   
    set<string> filter_accounts;  
    time_point_sec newest_date;  
    bool unread_only;  
    uint16_t limit;  
    uint32_t offset  
};

Параметры: select_accounts — список имен аккаунтов, выбранных для просмотра их сообщений; filter_accounts — список имен аккаунтов, исключенных для просмотра их сообщений; newest_date — дата и время, начиная с которого показываются сообщения; unread_only — показывать только непрочитанные сообщения; limit — максимальное количество выдаваемых сообщений; offset — смещение относительно начала списка, с которого выдаются сообщения.

Получение списка входящих сообщений для аккаунта-получателя сообщений

Для получения списка входящих сообщений для аккаунта-получателя используется запрос следующего вида:

get_inbox(
    string to, 
    message_box_query
)

Параметры: to — имя аккауна-получателя сообщений; message_box_query — запрос на получение сообщений;

Результатом является получение пользователем вектора вида: vector<message_api_object>.

Получение списка исходящих сообщений для аккаунта-отправителя сообщений

Для получения списка исходящих сообщений для аккаунта-отправителя используется запрос следующего вида:

get_outbox(
    from, 
    message_box_query
)

Параметры: from — имя аккауна-отправителя сообщений; message_box_query — запрос на получение сообщений.

Результатом запроса является получение пользователем вектора вида: vector<message_api_object>.

Фильтрация списка сообщений

Фильтрации списка сообщений в канале сообщений (между пользователями from и to) выполняется с использованием структуры следующего вида:

struct message_thread_query {
    time_point_sec newest_date;  
    bool unread_only;  
    uint16_t limit;  
    uint32_t offset
};

Параметры: newest_date — дата и время, начиная с которого показываются сообщения; unread_only — показывать только непрочитанные сообщения; limit — максимальное количество выдаваемых сообщений; offset — смещение относительно начала списка, с которого выдаются сообщения.

Получение потока сообщений между отправителем и получателем сообщений

Получение потока сообщений (между пользователями from и to) выполняется с использованием метода следующего вида:

get_thread(
    string from,
    string to, 
    message_thread_query
)

Параметры: from — имя аккаунта-отправителя сообщений; to — имя аккаунта-получателя сообщений; message_thread_query — запрос на получение потока сообщений.

Результатом запроса является получение пользователем вектора вида: vector<message_api_object>.

Получение актуальных настроек модуля личных сообщений

Для получения актуальных настроек модуля личных сообщений используется API-запрос следующего вида:

get_settings(string owner)

Параметр: owner — имя аккаунта, собственника контакт-листа.

Результатом запроса является получение структуры следующего вида:

struct settings_api_object {
    bool ignore_messages_from_unknown_contact;
};

Параметр: ignore_messages_from_unknown_contact — “true”, если блокируются сообщения от неизвестных контактов.

Получение данных о размерах контакт-листа

Для получения данных о размерах контакт листа используется запрос следующего вида:

get_contacts_size(string owner)

Параметр: owner — имя аккаунта, собственника контакт-листа.

Результатом запроса является получение структуры следующего вида:

struct contacts_size_api_object {
    map<private_contact_type, contacts_size_info> size
};

Параметры: size — данные размера контакт-листа в виде следующей структуры:

struct contacts_size_info {  
    int total_contacts;  
    int total_outbox_messages;  
    int unread_outbox_messages;  
    int total_inbox_messages;  
    int unread_inbox_messages  
};

total_contacts — общее количество имен аккаунтов (контактов) в контакт-листе; total_outbox_messages — общее количество исходящих сообщений; unread_outbox_messages — общее количество непрочитанных исходящих сообщений; total_inbox_messages — общее количество входящих сообщений; unread_inbox_messages — общее количество непрочитанных входящих сообщений

Получения данных об отдельно взятом контакте

Для получения данных об отдельно взятом контакте используется запрос следующего вида:

get_contact_info(
    string owner, 
    string contact
)

Параметры: owner — имя аккаунта, собственника контакт-листа; contact — имя аккаунта, данные о котором требуется получить.

Результатом запроса является получение структуры следующего вида:

struct contact_api_object {
    account_name_type owner;
    account_name_type contact;
    string json_metadata;
    private_contact_type local_type;
    private_contact_type remote_type;
    contact_size_info size
};

Параметры: owner — имя аккаунта, собственника контакт-листа (не более 16 символов); contact — имя контакта, данные о котором выдаются (не более 16 символов); json_metadata — данные об аккаунте в формате JSON; local_type — тип контакта в контакт-листе аккаунта с именем owner; remote_type — тип контакта в контакт-листе аккаунта с именем contact; size — данные размера контакт-листа.

Получения полного списка контактов, имеющихся в контакт-листе

Для получения полного списка имен аккаунтов (контактов), имеющихся в контакт-листе, используется запрос следующего вида:

get_contacts(
    string owner,
    private_contact_type type,
    int limit,
    int offset
)

Параметры: owner — имя аккаунта, собственника контакт-листа; type — тип контактов, список которых требуется получить (unknown, pinned, ignored); limit — максимальное количество выдаваемых контактов; offset — смещение относительно начала списка, с которого выдаются контакты.

Результатом запроса является получение массива структур вида vector<contact_api_object>.

Подписка на события о личных сообщениях

Для подписки на события о личных сообщениях используется вызов следующего вида:

set_callback(callback_query)

Параметр callback_query в этом вызове является структурой следующего вида:

struct callback_query {
    set<account_name_type> select_accounts;  
    set<account_name_type> filter_accounts;  
    set<callback_event_type> select_events;  
    set<callback_event_type> filter_events  
};

Параметры: select_accounts — список имен аккаунтов, выбранных для просмотра их сообщений; filter_accounts — список имен аккаунтов, исключенных для просмотра их сообщений; select_events — список событий для мониторинга; filter_events — список событий для исключения из мониторинга.

Список событий является перечислением следующего вида:

enum callback_event_type {
    message,     // мониторинг сообщений
    mark,        // пометка сообщений как прочитанных
    remove_inbox,     // удаление входящих сообщений
    remove_outbox,     // удаление исходящих сообщений
    contact        // добавление имени аккаунта в контакт-лист
};

На события message, mark, remove_inbox и remove_outbox будет приходить структура следующего вида:

struct callback_message_event {
    callback_event_type type;  // тип контакта (`unknown`,  `pinned`, `ignored`)
    message_api_object message // объект сообщения 
};

На события contact будет приходить структура следующего вида:

struct callback_contact_event {
    callback_event_type type; // тип контакта (`unknown`,  `pinned`, `ignored`)
    contact_api_object contact // объект контакта
};

Расширение возможностей пользователя с операциями над реблогами

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

Удаление реблога

В новой версии, в отличие от предыдущих версий, блоггеру предоставляется возможность удалять реблоги, а также скопированные случайным образом в его блог сторонние публикации. Для этого в плагин follow добавлен новый метод delete_reblog_operation(). Вызов этого метода возможен из cli_wallet с использованием эвалюатора custom_json. Операция удаления реблога формируется в ручном режиме.

Пример вызова операции удаления реблога:

begin_builder_transaction
add_operation_to_builder_transaction 0 ["custom_json", {"required_posting_auths":["<reblogger-name>"], \
    "id": "follow", "json":"["delete_reblog", {"account":"<reblogger-name>","author":"<post-author-name>", \
    "permlink":"<post-title>"}]"}]
sign_builder_transaction 0 true

В приведенном примере: begin_builder_transaction — команда вызова транзакции, в состав которой входит операция удаления реблога; add_operation_to_builder_transaction — команда, формирующая операцию удаления реблога, которой присвоен идентификационный номер “0”; <reblogger-name> — имя аккаунта-реблоггера, скопировавшего в свой блог сторонний пост; <post-author-name> — имя аккаунта оригинального поста; <post-title> — заголовок удаляемого реблога; sign_builder_transaction — команда для получения одобрения транзакции с отправлением ее на демон.

Для удаления более одного реблога необходимо сформировать транзакцию с несколькими операциями.

Добавление комментария к реблогу

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

Изменения в клиентском приложении cli_wallet

Для добавления комментария в реблог в вызываемую из приложения cli_wallet операцию reblog_operation добавлены следующие поля:

Имя поля	Тип	Назначение
body	string (UTF-8)	Содержит тело добавляемого к реблогу комментария
title	string (UTF-8)	Содержит заголовок добавляемого к реблогу комментария
json_metadata	string (UTF-8)	Содержит метаданные добавляемого комментария в формате JSON

Примечание: Наличие поля body в вызове является обязательным для операции реблога поста с добавлением комментария.

Пример вызова операции реблога поста с добавлением комментария:

begin_builder_transaction
add_operation_to_builder_transaction 0 ["custom_json", {"required_posting_auths":["<reblogger-name>"], \
    "id": "follow", "json":"["reblog", {"account":"<reblogger-name>","author":"<post-author-name>", \
    "permlink":"<post>","title":"<comment-title>","body":"<comment-body>"}]"}]
sign_builder_transaction 0 true

В приведенном примере: begin_builder_transaction — команда вызова транзакции, в состав которой входит операция реблога поста с добавлением комментария; add_operation_to_builder_transaction — команда, формирующая операцию реблога поста с добавлением комментария, которой присвоен идентификационный номер “0”; <reblogger-name> — имя аккаунта-блоггера, выполняющего реблог поста; <post-author-name> — имя аккаунта, автора оригинального поста; <post> — копируемый пост; <comment-title> — заголовок добавляемого комментария; <comment-body> — тело добавляемого комментария; sign_builder_transaction — команда для получения одобрения транзакции с отправлением ее на демон.

Изменения в API-методах:

Ответы API-методов get_blog и get_blog_entries дополнены полями, приведенными в следующей таблице:

Имя поля	Тип	Назначение
reblog_title	string	Содержит заголовок реблога, к которому добавляется комментарий
reblog_body	string	Содержит тело реблога
reblog_json_metadata	string	Содержит метаданные реблога

Ответы API-методов get_feed, get_feed_entries, get_discussions_by_blog и get_discussions_by_feed дополнены массивом объектов reblog_entries, структура которого дополнена полями, приведенными в следующей таблице:

Имя поля	Тип	Назначение
author	string	Содержит имя аккаунта-блоггера
reblog_title	string	Содержит заголовок реблога, к которому добавляется комментарий
reblog_body	string	Содержит тело реблога
reblog_json_metadata	string	Содержит метаданные реблога

Возможность настройки конфигурационного файла для хранения только необходимой информации на Узле

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

Для хранения на Узле блокчейна только важную информацию пользователю нет необходимости создавать Узел в варианте полной конфигурации памяти. Для снижения потребления ресурсов памяти пользователь мог построить Узел в варианте конфигурации LOW_MEM.

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

Возможность настройки конфигурационного файла для хранения метаданных аккаунта

В версии SF-0.18.4 для хранения метаданных аккаунта на Узле блокчейна (без перестроения Узла в варианте конфигурации LOW_MEM) добавлены новые флаги store-account-metadata и store-account-metadata-list в конфигурационный файл config.ini, а также внесены изменения в API-библиотеку. Использование этих флагов обеспечивает более гибкое настройку Узла для хранения важной информации в режиме сбережения памяти.

Для включения или выключения режима на хранение метаданных аккаунта пользователю достаточно настроить конфигурационный файл config.ini и один раз перезапустить Узел. По завершении синхронизации Узла в дальнейшем его перезапуск не требуется.

Изменения в конфигурационном файле config.ini Файл config.ini дополнен настраиваемыми флагами, приведенными в следующей таблице:

Имя флага	Тип	Значение по умолчанию	Устанавливаемое значение
store-account-metadata	bool	—	“true” — включение режима на хранение метаданных для всех аккаунтов, заданными в списке флага store-account-metadata-list. "false" — выключение режима на хранение метаданных для всех аккаунтов
store-account-metadata-list	string	—	Список имен аккаунтов, для которых сохраняются метаданные

Изменение в API-библиотеке API-метод account_api_object() использует пустое значение json_metadata без необходимости задания режима LOW_MEM для случая, если у Узла блокчейна выключен режим хранения метаданных.

Возможность настройки конфигурационного файла для хранения сопроводительной информации в операциях перевода средств

В версии SF-0.18.4 для хранения на Узле блокчейна (без перестроения Узла в варианте конфигурации LOW_MEM) сопроводительного текста поля memo в операциях перевода средств из кошельков добавлен новый флаг store-memo-in-savings-withdraws в конфигурационный файл config.ini. Использование этого флага обеспечивает более гибкое задание режима сбережения памяти.

Для включения или выключения режима на хранение сопроводительного сообщения поля memo пользователю достаточно настроить конфигурационный файл config.ini и всего один раз перезапустить Узел. По завершении синхронизации Узла в дальнейшем его перезапуск не требуется.

Изменения в конфигурационном файле config.ini Файл config.ini дополнен настраиваемым флагом, приведенным в следующей таблице:

Имя флага	Тип	Значение по умолчанию	Устанавливаемое значение
store-memo-in-savings-withdraws	bool	true	"true" — включение режима на хранение сообщения поля memo для всех операций по переводу средств из кошельков

Возможность настройки конфигурационного файла для хранения изменений в постах и комментариях с учетом глубины истории этих изменений

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

В версии SF-0.18.4 для устранения этого недостатка введен новый флаг store-comment-last-update в конфигурационный файл config.ini, а также внесены изменения в API-библиотеку. Использование этого флага предоставляет пользователю возможность устанавливать глубину истории хранения с учетом даты изменения и даты последнего обновления. Для включения или выключения режима на хранение комментариев полей last_update и active необходимо настроить конфигурационный файл config.ini и перезапустить Узел. По завершении синхронизации Узла в дальнейшем его перезапуск не требуется.

Изменения в конфигурационном файле config.ini Файл config.ini дополнен настраиваемым флагом, приведенным в следующей таблице:

Имя флага	Тип	Значение по умолчанию	Устанавливаемое значение
store-comment-last-update	bool	true	“true” — включение режима на хранение изменений в постах и комментариях. “false” — выключение режима

Изменения в API-библиотеке В версии SF-0.18.4 поля last_update и active являются произвольными и в возвращаемом значении API-метода comment_api_object() могут отсутствовать.

Изменены имена аргументов, представленных в следующей таблице.

Имя аргумента в предыдущей версии	Имя аргумента в версии SF-0.18.4
discussion_helper::impl fill_comment_content	fill_comment_info
discussion_helper::discussion_helper() fill_comment_content	fill_comment_info

Возможность настройки конфигурационного файла для хранения истории о вознаграждениях за публикации

После окончания выплат в виде вознаграждений автору за публикацию поста, а также лицам, принимавшим участие в голосовании, данные о выплатах становятся неактуальными и в дальнейшем не используются в системе. Пользователь, в случае необходимости, может хранить на своем Узле историю о вознаграждениях за публикации и использовать ее по своему усмотрению без необходимости перестроения Узла в варианте конфигурации LOW_MEM. В конфигурационный файл config.ini добавлена новая переменная store-comment-rewards, а также внесены изменения в API-библиотеку. Использование этой переменной обеспечивает хранение на Узле блокчейна историю выплат вознаграждений без необходимости перестроения Узла в варианте конфигурации LOW_MEM. Изменения в API-библиотеке Структура объекта комментариев дополнена новыми параметрами (помечены комментарием “новый”):

struct comment_api_object {
    …
    asset total_payout_value;
    asset beneficiary_payout_value;
    asset beneficiary_gests_payout_value;
    asset curator_payout_value;
    asset curator_gests_payout_value; // новый

    share_type author_rewards;
    asset author_gbg_payout_value; // новый 
    asset author_golos_payout_value; // новый
    asset author_gests_payout_value; // новый
    …
}

Параметры: total_payout_value — общая сумма выплат в GBG; beneficiary_payout_value — бенефициарские выплаты в GBG; beneficiary_gests_payout_value — бенефициарские выплаты в GESTS; curator_payout_value — кураторские выплаты в GBG; curator_gests_payout_value — кураторские выплаты в GESTS. author_rewards — авторские вознаграждения в GOLOS; author_gbg_payout_value — авторские выплаты в GBG; author_golos_payout_value — авторские выплаты в GOLOS; author_gests_payout_value — авторские выплаты в GESTS.

Возможность настройки конфигурационного файла для хранения истории постов или комментариев

Пользователю предоставляется возможность более гибко настраивать конфигурационный файл для хранения контента поста или комментариев до определенного времени. Конфигурационный файл config.ini дополнен новыми параметрами comment-title-depth, comment-body-depth, comment-json-metadata-depth и set-content-storing-depth-null-after-update.

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

Параметр set-content-storing-depth-null-after-update используется для случая, когда контент необходимо сохранять только после его изменения. Задание этого параметра автоматически отменяет действие первых трех параметров.

Для сбережения ресурсов памяти пользователь может сохранять контент не полностью, а только определенную его часть без необходимости перестроения Узла в варианте конфигурации LOW_MEM.

Параметры приведены в следующей таблице.

Имя параметра	Тип	Значение по умолчанию	Устанавливаемое значение
comment-title-depth	uint32_t	—	Максимальное количество блоков для хранения заголовков
comment-body-depth	uint32_t	—	Максимальное количество блоков для хранения тела поста или комментария
comment-json-metadata-depth	uint32_t	—	Максимальное количество блоков для хранения метаданных в формате JSON
set-content-storing-depth-null-after-update	bool	"false"	"true", если глубина хранения контента должна обнуляться после изменения контента

Возможность настройки конфигурационного файла для удаление устаревшей информации

В предыдущих версиях удаление устаревших голосов (объектов) выполнялось с помощью опции LOW_MEMORY_NODE, которая могла быть установлена либо в командной строке, либо в конфигурационном файле с помощью флага компиляции «–DLOW_MEMORY_NODE=ON/OFF». Удаление голосов выполнялось после закрытия поста и проведения всех необходимых расчетов с целью освобождения памяти от устаревшей информации и, следовательно, сокращения времени, затрачиваемое на начальную синхронизацию. Также удаление голосов можно было выполнить с помощью другой опции clear-votes-before-block, bpo::value<uint32_t>()->default_value(0), обеспечивающей удаление всех голосов до определенного фиксированного блока. Недостаток такого способа был в том, что он не обеспечивал удаление вновь пришедших голосов, которые заново накапливались в системе и по истечении определенного времени также становились ненужными.

Для удаления устаревших голосов в версии SF-0.18.4 конфигурационный файл config.ini дополнен новым параметром clear-votes-older-n-blocks, bpo::value<uint32_t>()->default_value(0xFFFFFFFF) обеспечивающим сохранение голосов N блоков и удаление голосов в блоках старше N. Соответствие задаваемого значения N и выполняемой операции приведено в следующей таблице.

Значение N	Количество блоков с сохраняемыми голосами	Выполняемая операция	Комментарий
N = 0	0	Удаление голосов сразу после закрытия поста	Используется для случая, когда не требуется сохранения голосов
N > 0	N	Удаление голосов в блоках старше N	Используется для сохранения голосов N блоков от текущего и удаления голосов в блоках старше N. Значение N показывает разность (возраст) между текущим блоком и блоком, в котором есть голос
N = -1	Все блоки	Удаление голосов не выполняется	Значение «-1» преобразуется в максимально возможное беззнаковое число (аналог бесконечности). Используется для хранения голосов длительное время

Во всех случаях удаление голосов не выполняется до закрытия поста.

Примечание: Доработка выполнена по просьбе делегатов.

Возможность настройки конфигурационного файла для увеличения количества ключевых слов или фраз для поиска нужной информации в постах

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

В новой версии максимальное количество тегов в запросе к Узлу блокчейна может быть увеличено до 15 включительно. Кроме этого, введено ограничение на размер тега, составляющее 512 символов. В конфигурационный файл config.ini добавлены параметры tags-number и tag-max-length, с помощью которых пользователь может задать количество и размер тега по своему усмотрению, что позволяет пользователю более гибко настраивать работу блокчейна.

Изменения в конфигурационном файле config.ini Параметры tags-number и tag-max-length приведены в следующей таблице.

Имя	Тип	Значение по умолчанию	Комментарий
tags-number	std::size_t	5	Это значение может быть увеличено до 15 включительно
tag-max-length	std::size_t	512	Не рекомендуется устанавливать размер тега более 512 символов

В случае принимаемого значения параметра tags-number по умолчанию доработка имеет обратную совместимость с предыдущими версиями.

Устранение недостатка в работе приложения cli_wallet с аккаунтом, имеющим несколько авторизаций

В предыдущих версиях возникала сложность с подписанием аккаунтом транзакции, если этот аккаунт имел возможность авторизоваться ключами сторонних аккаунтов. Перечень имен сторонних аккаунтов содержался в поле account_auths. Транзакции, создаваемые аккаунтом могли быть подписаны только ключами сторонних аккаунтов из поля account_auths. При попытке подписать транзакцию ключом основного аккаунта приложение cli_wallet выдавало сообщение об ошибке. Для устранения этого недостатка в версии SF-0.18.4 доработан метод annotated_signed_transaction() приложения cli_wallet с сохранением перечня входных и выходных параметров этого метода. Доработка обеспечила возможность подписывать транзакцию как ключами аккаунтов с именами из поля account_auths, так и ключом основного аккаунта.

Устранение недостатка в отображении авторов в ленте публикаций

Недостаток в отображаемой информации в ленте публикаций проявлялся в случае, когда автор, на публикации которого у пользователя была подписка, перепубликовывал работу стороннего автора. В результате в ленте публикаций отображалась информация о стороннем авторе, на публикации которого у пользователя не было подписки. Из-за отсутствия сообщения о причине его появления у пользователя возникало сложности в восприятии отображаемой информации на ленте публикаций. В версии 0.18.4 лента публикаций дополнена полем "reblogged_by:<a name>", в котором отображается имя автора, перепубликовавшего работу стороннего автора.

Фильтрация запрашиваемой информации об операциях из истории аккаунта

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

Изменения в API-методе get_account_history В метод добавлен произвольный параметр query для фильтрации операций. По умолчанию фильтрация отключена. Метод имеет следующий вид:

get_account_history(account_name, [from, [limit, [query]]])

Параметры from и limit в методе являются произвольными и по умолчанию принимают значения «-1» «100» соответственно. Метод может быть вызван с одним заданным параметром (например, get_account_history(account)) для получения 100 последних операций аккаунта. Параметр query является структурой (объектом) и содержит следующие поля: select_ops — перечень операций, которые необходимо получить. Значение может содержать имена операций (в том числе оканчивающие на «_operation»), а также ключевые слова: ALL — все операции; REAL — только операции явно заданные; VIRTUAL — только виртуальные операции; filter_ops — перечень операций, которые следует исключить. Принимает те же значения, что и select_ops. Это поле является произвольным и по умолчанию принимает значение пусто; direction — «направление» операции относительно аккаунта. Это поле является произвольным и принимает следующие значения: any — отсутствие направления фильтрации (значение по умолчанию); sender — характеризует аккаунта как отправителя (например, creator или voter); receiver— характеризует аккаунта как получателя (например, created или voted); dual — характеризует аккаунта как отправителя и получателя одновременно (например, voting self post или операция неоднозначно определяющая аккаунта).

Изменения в клиентском приложении cli_wallet Приложение cli_wallet дополнено методом filter_account_history(), который выполняет те же функции, что и метод get_account_history(). В отличие от последнего имеет входной параметр query для поддержки фильтрации. Примеры вызова filter_account_history():

get_account_history cyberfounder -1 100
filter_account_history cyberfounder -1 100 {"select_ops":["REAL","interest"], "filter_ops":["transfer"]}
filter_account_history cyberfounder -1 100 {"direction":"receiver","filter_ops":["producer_reward"]}