28 KiB
06. Channels Read API
Человеко-читаемое объяснение
Эти функции — это чтение данных каналов для UI:
-
ListSubscriptionsFeed— отдает данные для экрана списка каналов:- ваши каналы (личный + созданные вами),
- каналы пользователей, на кого вы подписаны,
- отдельные каналы, на которые вы подписаны напрямую.
-
GetChannelMessages— отдает полную ленту одного канала (пока без курсоров, загружается сразу целиком), включая версии сообщений, лайки и ответы. -
GetMessageThread— отдает дерево обсуждения вокруг конкретного сообщения: предки, фокус-сообщение, потомки. -
GetMessageLikes— отдает списки пользователей, поставивших лайк сообщению, сгруппированные для UI по статусу профиля. -
GetPersonalDiary— отдает виртуальную лентуЛичный дневник, собранную изSTATUS_ACTIONтекущего пользователя. -
GetChannelsCounters— отдает счетчики разделов каналов для пользователя. -
SetChannelReadState— сохраняет подписанный watermark чтения канала и возвращает новый unread-счетчик. -
ListGroupChats200— отдает список групповых чатов типа200. -
GetGroupDialog— отдает сообщения конкретного группового чата типа200.
На первом этапе мы не используем курсоры (
nextCursor) и загружаем полные списки.
unreadCountдля канала считается по подписанному состоянию чтения канала. Для собственных каналов владельцу всегда возвращаетсяunreadCount = 0, чтобы его собственные публикации не становились «новыми» для него самого. Если для парыownerBlockchainName/channelNameещё нет записи, канал временно считается полностью прочитанным. После появления записи новые публикации увеличиваютunreadCountдо продвижения курсора чтения.Для
FREE_CERTи платных пользователейListSubscriptionsFeedиспользует единый реестрuser_identity_current. Собственные каналы и личный корневой канал определяются поblockchain_nameиз этого реестра, без обязательного PDA в Solana. Подписки (connections_state) сопоставляются с логином без учёта регистра (в таблице связи нормализованы к нижнему регистру). Это обеспечивает одинаковую загрузку вкладок «Мои» и «Подписки» для бесплатных и платных аккаунтов. Сведения о публикациях в этих каналах также читаются с учётом активной цепочки из общего реестра.
ListSubscriptionsFeedтехнически может возвращать soft-deleted каналы сchannel.deleted=true, чтобы старые ссылки и selector канала продолжали разрешаться. Обычный UI скрывает такие строки. Для deleted-канала общий unread/counters не учитываются; сама подписка сохраняется.
1) ListSubscriptionsFeed
Request
{
"op": "ListSubscriptionsFeed",
"requestId": "req-1",
"payload": {
"login": "Alice",
"limit": 200
}
}
Response (success)
{
"op": "ListSubscriptionsFeed",
"requestId": "req-1",
"status": 200,
"ok": true,
"payload": {
"login": "Alice",
"ownedChannels": [
{
"channel": {
"ownerLogin": "Alice",
"ownerBlockchainName": "alice-001",
"channelName": "0",
"displayName": "Мой канал",
"channelDescription": "Короткое описание",
"avaAr": "ArweaveTxId...",
"avaSha256": "0123...",
"avaSize": 248193,
"metaUpdatedAtMs": 1760000000000,
"deleted": false,
"deletedAtMs": 0,
"deletedBlockNumber": null,
"personal": true,
"channelRoot": { "blockNumber": 0, "blockHash": "..." }
},
"messagesCount": 120,
"lastMessage": {
"messageRef": { "blockNumber": 921, "blockHash": "..." },
"text": "последняя версия текста",
"createdAtMs": 1760000000000,
"authorLogin": "Alice",
"authorBlockchainName": "alice-001"
}
}
],
"followedUsersChannels": [
{
"channel": {
"ownerLogin": "Bob",
"ownerBlockchainName": "bob-001",
"channelName": "0",
"personal": true,
"channelRoot": { "blockNumber": 0, "blockHash": "..." }
},
"messagesCount": 540,
"lastMessage": {
"messageRef": { "blockNumber": 922, "blockHash": "..." },
"text": "последняя версия текста",
"createdAtMs": 1760000100000,
"authorLogin": "Bob",
"authorBlockchainName": "bob-001"
}
}
],
"followedChannels": [
{
"channel": {
"ownerLogin": "Carl",
"ownerBlockchainName": "carl-001",
"channelName": "market",
"personal": false,
"channelRoot": { "blockNumber": 456, "blockHash": "..." }
},
"messagesCount": 90,
"readCount": 0,
"unreadCount": 0,
"readStateInitialized": false,
"lastMessage": {
"messageRef": { "blockNumber": 1002, "blockHash": "..." },
"text": "актуальный текст",
"createdAtMs": 1760001000000,
"authorLogin": "Carl",
"authorBlockchainName": "carl-001"
}
}
]
}
}
2) GetChannelMessages
Request
{
"op": "GetChannelMessages",
"requestId": "req-2",
"payload": {
"channel": {
"ownerBlockchainName": "bob-001",
"channelRootBlockNumber": 123,
"channelRootBlockHash": "..."
},
"limit": 200,
"sort": "asc"
}
}
limit необязателен. Если поле отсутствует или равно 0, сервер возвращает всю ленту канала. Положительное значение ограничивает количество сообщений для совместимых клиентов.
Response (success)
{
"op": "GetChannelMessages",
"requestId": "req-2",
"status": 200,
"ok": true,
"payload": {
"channel": {
"ownerLogin": "Bob",
"ownerBlockchainName": "bob-001",
"channelName": "news",
"displayName": "Новости Bob",
"channelDescription": "Канал о новостях",
"avaAr": "ArweaveTxId...",
"avaSha256": "0123...",
"avaSize": 248193,
"metaUpdatedAtMs": 1760000000000,
"deleted": false,
"deletedAtMs": 0,
"deletedBlockNumber": null,
"subscribersCount": 128,
"channelRoot": { "blockNumber": 123, "blockHash": "..." }
},
"metaEvents": [
{
"kind": "created",
"messageRef": { "blockNumber": 123, "blockHash": "..." },
"authorLogin": "Bob",
"authorBlockchainName": "bob-001",
"lineStep": 1,
"createdAtMs": 1760000000000,
"title": "news",
"description": "",
"avaAr": "",
"avaSha256": "",
"avaSize": 0
},
{
"kind": "profile_updated",
"messageRef": { "blockNumber": 130, "blockHash": "..." },
"authorLogin": "Bob",
"authorBlockchainName": "bob-001",
"lineStep": 2,
"createdAtMs": 1760000500000,
"title": "Новости Bob",
"description": "Канал о новостях",
"avaAr": "ArweaveTxId...",
"avaSha256": "0123...",
"avaSize": 248193
}
],
"messages": [
{
"messageRef": { "blockNumber": 140, "blockHash": "..." },
"authorLogin": "Bob",
"authorBlockchainName": "bob-001",
"createdAtMs": 1760000000000,
"text": "текущая версия",
"likesCount": 12,
"repliesCount": 3,
"ratingsCount": 2,
"versionsTotal": 4,
"versions": [
{ "versionIndex": 1, "blockNumber": 140, "blockHash": "...", "text": "v1", "createdAtMs": 1760000000000 },
{ "versionIndex": 2, "blockNumber": 155, "blockHash": "...", "text": "v2", "createdAtMs": 1760001000000 },
{ "versionIndex": 3, "blockNumber": 170, "blockHash": "...", "text": "v3", "createdAtMs": 1760002000000 },
{ "versionIndex": 4, "blockNumber": 199, "blockHash": "...", "text": "v4", "createdAtMs": 1760003000000 }
]
}
]
}
}
Для soft-deleted канала channel.deleted=true; deletedAtMs и deletedBlockNumber указывают последний delete-блок. В metaEvents delete-блоки возвращаются как kind: "deleted". После новой самостоятельной публикации канал снова активен (deleted=false), при этом исторические deleted meta-events остаются частью истории.
3) GetMessageThread
Request
{
"op": "GetMessageThread",
"requestId": "req-3",
"payload": {
"message": {
"blockchainName": "bob-001",
"blockNumber": 333,
"blockHash": "..."
},
"depthUp": 20,
"depthDown": 2,
"limitChildrenPerNode": 50
}
}
Response (success)
{
"op": "GetMessageThread",
"requestId": "req-3",
"status": 200,
"ok": true,
"payload": {
"ancestors": [MessageNode],
"focus": MessageNode,
"descendants": [MessageNodeTree]
}
}
MessageNode (дополнение)
MessageNodeрасширяет формат сообщения изGetChannelMessagesи дополнительно содержит:channelInfo— мета-информация о канале (если применимо);rawBlockB64— сыройblock_bytesтекущего блока в Base64.
- Поле
rawBlockB64присутствует у узлов во всех частях ответаGetMessageThread:focus,ancestors[],descendants[]. - В
GetChannelMessagesполеrawBlockB64не добавляется (лента канала без сырого блока, чтобы не раздувать ответ). - И в
GetChannelMessages, и вGetMessageThreadкаждое сообщение теперь содержит:repliesCount— число дочерних сообщений типаTEXT_REPLY;ratingsCount— число дочерних сообщений типаTEXT_RATING.
- В
descendants[]операцииGetMessageThreadвозвращаются оба типа дочерних текстовых сообщений:TEXT_REPLY;TEXT_RATING. Они идут в одной общей ветке обсуждения и сортируются по времени создания.
4) GetMessageLikes
Возвращает пользователей, которые поставили лайк конкретному сообщению канала.
message.blockchainName,message.blockNumber,message.blockHashдолжны указывать на исходное сообщение.limitв текущей реализации не требуется: сервер возвращает полный найденный список лайков.- Пользователи группируются по состоянию профиля:
shining—account_role=primaryиshine_status=shining;official—account_role=primary, но безshine_status=shining;others— остальные пользователи.
Request
{
"op": "GetMessageLikes",
"requestId": "req-4",
"payload": {
"message": {
"blockchainName": "bob-001",
"blockNumber": 140,
"blockHash": "..."
}
}
}
Response (success)
{
"op": "GetMessageLikes",
"requestId": "req-4",
"status": 200,
"ok": true,
"payload": {
"shining": [
{ "login": "Alice", "firstName": "Alice", "lastName": "", "avatarAr": "ArweaveTxId..." }
],
"official": [],
"others": [
{ "login": "Carl", "firstName": "", "lastName": "", "avatarAr": "" }
],
"total": 2,
"truncated": false
}
}
Ошибки
bad_fields— не переданmessageили обязательные поля ссылки на сообщение.bad_hash—message.blockHashне является корректным hex-хэшем блока.internal_error— внутренняя ошибка чтения.
truncated сейчас всегда false; поле оставлено в ответе для совместимости с UI и возможной будущей пагинацией.
5) GetPersonalDiary
Возвращает виртуальный канал Личный дневник для самого пользователя.
- Вызов доступен только владельцу дневника.
- Сообщения в ответе строятся из блоков
STATUS_ACTION. - Поля
targetMsgSubType,targetText,targetAuthorLogin,targetAuthorBlockchainName,targetCreatedAtMsописывают исходный материал, к которому относится действие.
Request
{
"op": "GetPersonalDiary",
"requestId": "req-4",
"payload": {
"login": "Alice",
"limit": 200,
"sort": "asc"
}
}
6) GetChannelsCounters
Request
{
"op": "GetChannelsCounters",
"requestId": "req-4",
"payload": {
"login": "Alice"
}
}
Response (success)
{
"op": "GetChannelsCounters",
"requestId": "req-4",
"status": 200,
"ok": true,
"payload": {
"login": "Alice",
"feedCount": 12,
"dialogs100Count": 3,
"groupChats200Count": 4,
"myChannelsCount": 2
}
}
7) SetChannelReadState
Сохраняет подписанную позицию чтения для одного канала, на который пользователь подписан.
- Требует авторизованное WebSocket-соединение.
loginдолжен совпадать с текущим авторизованным пользователем.- Подпись строится client key пользователя по строке:
SHiNe/ChannelReadState:<login>|<owner_bch_name>|<channel_name>|<time_ms>|<read_count>
Request
{
"op": "SetChannelReadState",
"requestId": "req-7",
"payload": {
"login": "Alice",
"owner_bch_name": "bob-001",
"channel_name": "news",
"read_count": 90,
"time_ms": 1760000000000,
"client_key": "<base64-client-public-key>",
"signature": "<base64-ed25519-signature>"
}
}
Response (success)
{
"op": "SetChannelReadState",
"requestId": "req-7",
"status": 200,
"ok": true,
"payload": {
"login": "Alice",
"owner_bch_name": "bob-001",
"channel_name": "news",
"read_count": 90,
"unread_count": 0,
"time_ms": 1760000000000,
"applied": true
}
}
Ошибки
NOT_AUTHENTICATED— нет авторизованной сессии.BAD_FIELDS— не переданы обязательные поля.LOGIN_MISMATCH—loginне совпадает с текущей сессией.BAD_TIME— время подписи слишком далеко в будущем.BAD_BASE64—client_keyилиsignatureне являются корректным Base64.DEVICE_KEY_MISMATCH—client_keyне совпадает с текущим client key пользователя.INVALID_SIGNATURE— подпись watermark не прошла проверку.CHANNEL_NOT_FOLLOWED— пользователь не подписан на канал.CHANNEL_NOT_FOUND— канал не найден.INTERNAL_ERROR— внутренняя ошибка записи.
8) ListGroupChats200
Request
{
"op": "ListGroupChats200",
"requestId": "req-5",
"payload": {
"login": "Alice"
}
}
Response (success)
{
"op": "ListGroupChats200",
"requestId": "req-5",
"status": 200,
"ok": true,
"payload": {
"login": "Alice",
"chats": [
{
"ownerLogin": "Alice",
"ownerBlockchainName": "alice-001",
"channelRootBlockNumber": 123,
"channelRootBlockHash": "...",
"channelName": "team",
"chatTitle": "Team chat",
"membersCount": 3,
"updatedAtMs": 1760000000000
}
]
}
}
9) GetGroupDialog
Request
{
"op": "GetGroupDialog",
"requestId": "req-6",
"payload": {
"login": "Alice",
"group": {
"ownerBlockchainName": "alice-001",
"channelRootBlockNumber": 123
}
}
}
Response (success)
{
"op": "GetGroupDialog",
"requestId": "req-6",
"status": 200,
"ok": true,
"payload": {
"group": {
"ownerLogin": "Alice",
"ownerBlockchainName": "alice-001",
"channelRootBlockNumber": 123,
"channelName": "team",
"chatTitle": "Team chat"
},
"messages": [
{
"authorLogin": "Bob",
"authorBlockchainName": "bob-001",
"blockNumber": 140,
"blockHash": "...",
"createdAtMs": 1760000000000,
"text": "Привет"
}
]
}
}
Reason codes
bad_fieldsuser_not_foundchannel_not_foundmessage_not_foundbad_limitchannel_name_already_existsCHANNEL_NOT_FOLLOWEDCHANNEL_NOT_FOUNDinternal_error
Profile public-channel lists (v18)
ListUserProfileChannels
Returns lightweight public-channel cards for profile counters. mode is owned or following; only channel_type_code=1 is returned.
{
"op": "ListUserProfileChannels",
"requestId": "profile-ch-1",
"payload": { "login": "Alice", "mode": "owned", "includeDeleted": false, "limit": 100, "offset": 0 }
}
includeDeleted необязателен и по умолчанию равен false. При true ответ включает как активные, так и soft-deleted каналы.
Channel items contain ownerLogin, slug, displayName, avatarAr, ownerBlockchainName, rootBlockNumber, rootBlockHashHex, deleted, deletedAtMs, and deletedBlockNumber.
Qualified likes (v18)
Channel/message responses expose three counters:
likesCount— all active likes;primaryLikesCount— likes from users whose currentaccount_role=primary;shiningLikesCount— likes from users who are currently bothprimaryandshining.
Changing account_role or shine does not alter the raw reaction. The two qualified counters are recalculated from reactions_state; therefore old likes automatically enter or leave qualified counters when the actor's current status changes.
SearchChannels — публичный поиск каналов (v32)
Операция без авторизации, на текущем сервере (не федеративный поиск).
Результаты берутся из актуального состояния channel_names_state; публичные каналы — channel_type_code = 1, не удалённые (is_deleted = false).
Запрос:
{
"op": "SearchChannels",
"requestId": "search-ch-1",
"payload": { "query": "гриб", "limit": 10 }
}
query— текст от 1 до 120 символов. Не обязателен, если указанownerLogin.ownerLogin— дополнительное ограничение по началу логина владельца, до 80 символов.limit— число результатов, по умолчанию 10, допустимо 1–50. Курсора и пагинации нет.@anna— каналы владельцев, чьи логины содержатanna.anna/art— каналы владельцаanna, у которых публичное либо техническое название содержитart.anna/— все доступные каналы владельцаanna.- В обычном запросе ищутся подстроки в публичном имени
display_name, техническомslugи логинеowner_login. Регистр не важен,ёприравнивается ке. Вводимые%,_и!не работают как SQL-маски. - Сначала идут точные совпадения с названием или slug, затем префиксные, затем частичные, далее учитывается количество подписчиков.
Ответ:
{
"op": "SearchChannels",
"requestId": "search-ch-1",
"status": 200,
"ok": true,
"payload": {
"channels": [{
"ownerLogin": "anna",
"slug": "fungal-art",
"displayName": "Грибной мир",
"description": "Картины и грибы",
"avatarAr": "",
"avatarSha256": "",
"ownerBlockchainName": "anna-001",
"rootBlockNumber": 12,
"rootBlockHashHex": "<hex>",
"subscribersCount": 128
}]
}
}
Массив channels пустой при отсутствии совпадений; URL не возвращается.
ownerBlockchainName и корневой блок позволяют клиенту открыть канонический канал через существующую маршрутизацию.
Неверные поля: HTTP-подобный статус 400, код BAD_FIELDS; ошибки чтения БД: SERVER_DATA_ERROR, DB_ERROR.
Структура блокчейна не меняется. Индексы поиска добавлены миграцией БД v32 (pg_trgm).
2026-10-28 — Официальный регистр логинов при чтении
В ответах GetChannelMessages, GetMessageThread, ListSubscriptionsFeed поля authorLogin и ownerLogin показывают регистрационное написание из user_identity_current, например AlexSmith@shine. В БД блока и в blockchainName по-прежнему возможен lowercase, используемый как нормализованный идентификатор. Это не меняет имена JSON-полей или типы значений, а уточняет их семантику. Для поиска и переходов разные варианты регистра по-прежнему ссылаются на одну идентичность; байты уже подписанных блоков не переписываются.
GetSupportTotals — проверенная поддержка канала
Запрос: {"op":"GetSupportTotals", "channelRootBlockNumber":12, "channelRootBlockHash":"<64 hex>"}.
Ответ (при status=200): channelReceivedLamports — десятичная строка суммы реально полученных авторами средств (90% донатов); messages — массив {blockNumber,blockHash,receivedLamports}. Все значения в lamports представлены строками, не JavaScript Number. В результате возвращаются не более 2000 сообщений с максимальными суммами, агрегат канала включает все проверенные операции.
API считает только support_user из таблицы solana_support_transfers. Для CHANNEL проверяет, что адресат равен владельцу существующего канала. Для MESSAGE проверяет наличие блока с точным номером/хешем, авторство получателя и принадлежность блока цепочке владельца канала. Не соответствующие этим условиям донаты остаются в истории, но не включаются в публичные суммы. Поддержка ответов в других пользовательских цепочках не попадает в агрегат до добавления полной проверки принадлежности обсуждению.
Таблицы истории автоматически создаются финансовым индексатором. Пока он не синхронизирован, операция может возвращать support_totals_unavailable — клиент не должен подменять отсутствие данных нулями.
GetSupportStats — публичные счётчики поддержки Paid-пользователя
Счётчики загружаются из PostgreSQL, а не через отдельный RPC Solana при каждом
открытии профиля. Серверный SupportHistoryIndexer собирает кеш из успешных
финализированных транзакций shine_users (opcodes 9 и 10). Исходная проверяемая
финансовая статистика хранится в Solana PDA; кеш может отставать до следующего sync.
Запрос:
{"op":"GetSupportStats","requestId":"support-1","payload":{"login":"Alice@namespace"}}
Ответ:
{
"op":"GetSupportStats", "requestId":"support-1", "status":200, "ok":true,
"payload":{
"login":"Alice@namespace", "available":true, "ready":true,
"supportSentLamports":"1000000000",
"supportReceivedLamports":"900000000",
"daoDirectLamports":"100000000"
}
}
available=false— локальный Solana sync не содержит Paid PDA (например, Free-аккаунт). Поля сумм в этом случае не показывать.ready=false— сервер ещё не закончил первичную индексацию всей доступной истории; суммы нельзя показывать как окончательные (даже если возвращены нули).available=true, ready=true, а строки сумм равны"0"— корректная нулевая статистика зарегистрированного Paid-пользователя без донатов.- Все значения lamports передаются строками (без преобразования в JS Number).
Показатель «Поддержал SHiNE» вычисляется как
supportSentLamports / 10 + daoDirectLamports. Регистрация и изменение PDA сюда не входят.
При отсутствии таблиц/соединения БД сервер возвращает ошибку, а не фиктивные нули.
API не запускает RPC-вызовы; для свежих значений сразу после оплаты необходимо
дождаться следующего прохода SupportHistoryIndexer.