Files
coopenomics/coopos/producer.swagger.yaml
Alex Ant 49188d404e update
2026-03-20 23:37:38 +05:00

893 lines
34 KiB
YAML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
openapi: 3.0.0
info:
title: API продюсера COOPOS
description: Спецификация Producer API узла COOPOS (nodeos). Включение плагина — в документации на https://coopenomics.world.
version: 1.0.0
license:
name: MIT
url: https://opensource.org/licenses/MIT
contact:
url: https://coopenomics.world
tags:
- name: Версия протокола 4.0
description: Тег релиза бинарников COOPOS совпадает с версией протокола
servers:
- url: "{protocol}://{host}:{port}/v1"
variables:
protocol:
enum:
- http
- https
default: http
host:
default: localhost
port:
default: "8080"
security:
- {}
paths:
/producer/pause:
post:
summary: Приостановить
description: Приостанавливает выпуск блоков узлом-продюсером. Без аргументов; тело ответа не задаётся.
operationId: pause
responses:
"201":
description: Успешно
content:
application/json:
schema:
$ref: "#/components/schemas/OK"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/resume:
post:
summary: Возобновить
description: Возобновляет выпуск блоков узлом-продюсером. Без аргументов; тело ответа не задаётся.
operationId: resume
responses:
"201":
description: Успешно
content:
application/json:
schema:
$ref: "#/components/schemas/OK"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/paused:
post:
summary: Статус паузы
description: Возвращает, приостановлен ли узел-продюсер. Без аргументов.
operationId: paused
responses:
"201":
description: Успешно
content:
text/plain:
schema:
description: Строка «true» или «false»
type: string
example: false
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/get_runtime_options:
post:
summary: Параметры времени выполнения
description: Возвращает текущие параметры времени выполнения узла-продюсера.
operationId: get_runtime_options
responses:
"201":
description: Успешно
content:
application/json:
schema:
$ref: "#/components/schemas/Runtime_Options"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/update_runtime_options:
post:
summary: Обновить параметры времени выполнения
description: Обновляет параметры времени выполнения узла-продюсера. Можно передать любое подмножество полей.
operationId: update_runtime_options
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Runtime_Options"
responses:
"201":
description: Успешно
content:
application/json:
schema:
$ref: "#/components/schemas/OK"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/get_greylist:
post:
summary: Список серой зоны
description: Возвращает серый список (greylist) узла-продюсера.
operationId: get_greylist
responses:
"201":
description: Успешно
content:
application/json:
schema:
type: object
properties:
accounts:
type: array
description: Имена учётных записей в сером списке
items:
$ref: "schemas/Name.yaml"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/add_greylist_accounts:
post:
summary: Добавить в серый список
description: Добавляет учётные записи в серый список узла-продюсера. Нужна хотя бы одна запись.
operationId: add_greylist_accounts
requestBody:
content:
application/json:
schema:
type: object
properties:
accounts:
type: array
description: Имена учётных записей для добавления
items:
$ref: "schemas/Name.yaml"
responses:
"201":
description: Успешно
content:
application/json:
schema:
$ref: "#/components/schemas/OK"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/remove_greylist_accounts:
post:
summary: Убрать из серого списка
description: Удаляет учётные записи из серого списка узла-продюсера. Нужна хотя бы одна запись.
operationId: remove_greylist_accounts
requestBody:
content:
application/json:
schema:
type: object
properties:
accounts:
type: array
description: Имена учётных записей для удаления
items:
$ref: "schemas/Name.yaml"
responses:
"201":
description: Успешно
content:
application/json:
schema:
$ref: "#/components/schemas/OK"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/get_whitelist_blacklist:
post:
summary: Белые и чёрные списки
description: Возвращает белые и чёрные списки узла-продюсера в виде JSON-объекта.
operationId: get_whitelist_blacklist
responses:
"201":
description: Успешно
content:
application/json:
schema:
type: object
properties:
actor_whitelist:
type: array
items:
$ref: "schemas/Name.yaml"
actor_blacklist:
type: array
items:
$ref: "schemas/Name.yaml"
contract_whitelist:
type: array
items:
$ref: "schemas/Name.yaml"
contract_blacklist:
type: array
items:
$ref: "schemas/Name.yaml"
action_blacklist:
type: array
items:
type: array
description: Два элемента — имя контракта и имя действия
items:
allOf:
- $ref: "schemas/Name.yaml"
- $ref: "schemas/CppSignature.yaml"
key_blacklist:
type: array
items:
- $ref: "schemas/KeyType.yaml"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/set_whitelist_blacklist:
post:
summary: Задать белые и чёрные списки
description: Задаёт белые и чёрные списки узла-продюсера. Тело запроса — JSON с полями списков.
operationId: set_whitelist_blacklist
requestBody:
content:
application/json:
schema:
type: object
properties:
actor_whitelist:
type: array
items:
$ref: "schemas/Name.yaml"
actor_blacklist:
type: array
items:
$ref: "schemas/Name.yaml"
contract_whitelist:
type: array
items:
$ref: "schemas/Name.yaml"
contract_blacklist:
type: array
items:
$ref: "schemas/Name.yaml"
action_blacklist:
type: array
items:
type: array
description: Два элемента — имя контракта и имя действия
items:
anyOf:
- $ref: "schemas/Name.yaml"
- $ref: "schemas/CppSignature.yaml"
key_blacklist:
type: array
items:
$ref: "schemas/KeyType.yaml"
responses:
"201":
description: Успешно
content:
application/json:
schema:
$ref: "#/components/schemas/OK"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/create_snapshot:
post:
summary: Создать снимок
description: Создаёт снимок состояния узла-продюсера. При ошибке возвращает ответ с ошибкой.
operationId: create_snapshot
responses:
"201":
description: Успешно
content:
application/json:
schema:
type: object
properties:
head_block_id:
$ref: "schemas/Sha256.yaml"
head_block_num:
type: integer
description: Номер головного блока цепи
example: 5102
head_block_time:
type: string
description: Метка времени головного блока (Unix)
example: 2020-11-16T00:00:00.000
version:
type: integer
description: Номер версии формата снимка
example: 6
snapshot_name:
type: string
description: Путь и имя файла снимка
example: /home/me/nodes/node-name/snapshots/snapshot-0000999f99999f9f999f99f99ff9999f999f9fff99ff99ffff9f9f9fff9f9999.bin
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/schedule_snapshot:
post:
summary: Запланировать снимки
description: Запрашивает периодическое создание снимков по заданным параметрам. Пустое тело — немедленное создание снимка. При невозможности принять расписание — ошибка.
operationId: schedule_snapshot
requestBody:
content:
application/json:
schema:
type: object
properties:
block_spacing:
type: integer
description: Создавать снимок каждые block_spacing блоков
start_block_num:
type: integer
description: Номер блока начала расписания
example: 5102
end_block_num:
type: integer
description: Номер блока окончания расписания
example: 15102
snapshot_description:
type: string
description: Описание снимка / задания
example: Daily snapshot
responses:
"201":
description: Успешно
content:
application/json:
schema:
type: object
required:
- snapshot_request_id
- block_spacing
- start_block_num
- end_block_num
- snapshot_description
properties:
snapshot_request_id:
type: integer
description: Уникальный идентификатор запроса на снимки
block_spacing:
type: integer
description: Создавать снимок каждые block_spacing блоков
start_block_num:
type: integer
description: Номер блока начала расписания
example: 5102
end_block_num:
type: integer
description: Номер блока окончания расписания
example: 15102
snapshot_description:
type: string
description: Описание снимка / задания
example: Daily snapshot
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/get_snapshot_requests:
post:
summary: Список запланированных снимков
description: Возвращает список запросов на периодические снимки.
operationId: get_snapshot_requests
responses:
"201":
description: Успешно
content:
application/json:
schema:
type: object
properties:
snapshot_requests:
type: array
description: Запланированные запросы на снимки
items:
type: object
required:
- snapshot_request_id
- block_spacing
- start_block_num
- end_block_num
- snapshot_description
- pending_snapshots
properties:
snapshot_request_id:
type: integer
description: Уникальный идентификатор запроса на снимки
block_spacing:
type: integer
description: Создавать снимок каждые block_spacing блоков
start_block_num:
type: integer
description: Номер блока начала расписания
example: 5102
end_block_num:
type: integer
description: Номер блока окончания расписания
example: 15102
snapshot_description:
type: string
description: Описание снимка / задания
example: Daily snapshot
pending_snapshots:
type: array
description: Ожидающие снимки
items:
type: object
required:
- head_block_id
- head_block_num
- head_block_time
- version
- snapshot_name
properties:
head_block_id:
$ref: "schemas/Sha256.yaml"
head_block_num:
type: integer
description: Номер головного блока цепи
example: 5102
head_block_time:
type: string
description: Метка времени головного блока (Unix)
example: 2020-11-16T00:00:00.000
version:
type: integer
description: Номер версии формата снимка
example: 6
snapshot_name:
type: string
description: Путь и имя файла снимка
example: /home/me/nodes/node-name/snapshots/snapshot-0000999f99999f9f999f99f99ff9999f999f9fff99ff99ffff9f9f9fff9f9999.bin
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/unschedule_snapshot:
post:
summary: Отменить расписание снимков
description: Удаляет запрос на снимки по идентификатору. Ошибка, если такого запроса нет.
operationId: unschedule_snapshot
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
snapshot_request_id:
type: integer
description: Идентификатор запроса на снимки
responses:
"201":
description: Успешно
content:
application/json:
schema:
type: object
required:
- snapshot_request_id
- block_spacing
- start_block_num
- end_block_num
- snapshot_description
properties:
snapshot_request_id:
type: integer
description: Уникальный идентификатор запроса на снимки
block_spacing:
type: integer
description: Создавать снимок каждые block_spacing блоков
start_block_num:
type: integer
description: Номер блока начала расписания
example: 5102
end_block_num:
type: integer
description: Номер блока окончания расписания
example: 15102
snapshot_description:
type: string
description: Описание снимка / задания
example: Daily snapshot
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/get_integrity_hash:
post:
summary: Хеш целостности
description: Возвращает хеш целостности состояния узла-продюсера.
operationId: get_integrity_hash
responses:
"201":
description: Успешно
content:
application/json:
schema:
type: object
description: Данные хеша целостности
properties:
head_block_id:
$ref: "schemas/Sha256.yaml"
integrity_hash:
$ref: "schemas/Sha256.yaml"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/schedule_protocol_feature_activations:
post:
summary: Запланировать активацию протокольных возможностей
description: Планирует активацию протокольных возможностей на узле-продюсере. Часть возможностей требует предварительной активации. Дубликаты и нарушение порядка предварительной активации дают ошибку.
operationId: schedule_protocol_feature_activations
requestBody:
content:
application/json:
schema:
type: object
properties:
protocol_features_to_activate:
type: array
description: Список протокольных возможностей для активации
items:
$ref: "schemas/Sha256.yaml"
responses:
"201":
description: Успешно
content:
application/json:
schema:
$ref: "#/components/schemas/OK"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/get_supported_protocol_features:
post:
summary: Поддерживаемые протокольные возможности
description: Возвращает поддерживаемые узлом протокольные возможности. Фильтры передаются в теле запроса.
operationId: get_supported_protocol_features
requestBody:
content:
application/json:
schema:
type: object
properties:
exclude_disabled:
type: boolean
description: Исключить отключённые возможности
example: false
default: false
exclude_unactivatable:
type: boolean
description: Исключить возможности, которые нельзя активировать
default: false
example: false
responses:
"201":
description: Успешно
content:
application/json:
schema:
type: array
description: Массив объектов с описанием поддерживаемых протокольных возможностей
items:
type: object
properties:
feature_digest:
$ref: "schemas/Sha256.yaml"
subjective_restrictions:
type: object
properties:
enabled:
type: boolean
example: true
preactivation_required:
type: boolean
example: true
earliest_allowed_activation_time:
type: string
example: "1970-01-01T00:00:00.000"
description_digest:
$ref: "schemas/Sha256.yaml"
dependencies:
type: array
items:
$ref: "schemas/Sha256.yaml"
protocol_feature_type:
type: string
example: "builtin"
specification:
type: array
items:
type: object
properties:
name:
type: string
value:
type: string
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/get_account_ram_corrections:
post:
summary: Корректировки RAM по аккаунтам
description: Возвращает учётные записи с корректировками RAM.
operationId: get_account_ram_corrections
requestBody:
content:
application/json:
schema:
type: object
properties:
lower_bound:
type: integer
description: Нижняя граница ключа аккаунта
upper_bound:
type: integer
description: Верхняя граница ключа аккаунта
limit:
type: integer
description: Число строк для обхода
default: 10
example: 10
reverse:
type: boolean
description: Направление обхода
example: false
default: false
responses:
"201":
description: Успешно
content:
application/json:
schema:
type: object
required:
- rows
properties:
rows:
type: array
items:
type: string
more:
type: array
items:
- $ref: "schemas/Name.yaml"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/producer/get_unapplied_transactions:
post:
summary: Неприменённые транзакции
description: Возвращает транзакции, ожидающие применения (неприменённые).
operationId: get_unapplied_transactions
requestBody:
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
description: Максимальное число транзакций в ответе
default: 100
example: 100
lower_bound:
$ref: "schemas/Sha256.yaml"
time_limit_ms:
type: integer
description: Лимит времени ответа (мс); по умолчанию как у http-max-response-time-ms узла
default: http-max-response-time-ms
example: 10
responses:
"200":
description: Успешно
content:
application/json:
schema:
type: object
properties:
size:
type: integer
default: 0
example: 12428
incoming_size:
type: integer
default: 0
example: 4475
trxs:
type: array
items:
type: object
properties:
trx_id:
$ref: "schemas/Sha256.yaml"
expiration:
type: string
example: "2022-09-17T16:30:16"
trx_type:
type: string
example: "aborted"
first_auth:
type: string
example: "jkbsg.wam"
first_receiver:
type: string
example: "m.federation"
first_action:
type: string
example: "mine"
total_actions:
type: integer
default: 0
example: 1
billed_cpu_time_us:
type: integer
default: 0
example: 504
size:
type: integer
default: 0
example: 934
more:
$ref: "schemas/Sha256.yaml"
"400":
description: Ошибка клиента
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
securitySchemes: {}
schemas:
Error:
type: object
properties:
code:
type: integer
description: HTTP-код ответа
example: 400
message:
type: string
description: Краткое описание ошибки
example: Invalid Request
error:
type: object
description: Подробности ошибки
properties:
code:
type: integer
description: Внутренний код ошибки
example: 3200006
name:
type: string
description: Имя ошибки
example: invalid_http_request
what:
type: string
description: Человекочитаемое описание ошибки
example: invalid http request
details:
type: array
description: Дополнительные сведения для отладки
items:
type: object
properties:
message:
type: string
description: Сообщение отладки
example: Unable to parse valid input from POST body
file:
type: string
description: Файл, в котором возникла ошибка
example: http_plugin.hpp
line_number:
type: integer
description: Номер строки в файле
example: 246
method:
type: string
description: Функция, при выполнении которой произошла ошибка
example: parse_params
OK:
type: object
properties:
result:
type: string
description: Статус операции
example: ok
Runtime_Options:
type: object
properties:
max_transaction_time:
type: integer
description: Максимальное время выполнения транзакции
example: 100
max_irreversible_block_age:
type: integer
description: Максимальный «возраст» необратимого блока
example: -1
produce_time_offset_us:
type: integer
description: Смещение времени производства (мкс)
example: -100000
last_block_time_offset_us:
type: integer
description: Смещение времени последнего блока (мкс)
example: -200000
max_scheduled_transaction_time_per_block_ms:
type: integer
description: Максимальное время отложенных транзакций на блок (мс)
example: 100
subjective_cpu_leeway_us:
type: integer
description: Допуск субъективного CPU (мкс)
example: 10
incoming_defer_ratio:
type: string
description: Доля входящих отложенных транзакций (строка, парсится в double)
example: "1.00000000000000000"
greylist_limit:
type: integer
description: Лимит числа имён (Name) в сером списке
example: 1000