# Черновик формата вложений в сообщениях блокчейна SHiNE

## Статус документа

Этот файл пока является черновиком и рабочим описанием идеи.

Важно:

- это не финальная спецификация;
- точная версия формата будет зафиксирована после начала реальной реализации;
- до момента реализации допустимы изменения полей, синтаксиса и правил отображения;
- документ специально лежит в корне проекта как временная рабочая заметка.

## Цель

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

Основная идея:

- само сообщение остаётся обычным текстом;
- вложения описываются специальными техническими вставками в начале текста;
- сами файлы хранятся отдельно в архиве/Arweave;
- в сообщении хранятся только метаданные, достаточные для отображения и скачивания.

## Общий принцип

Если в начале текста сообщения стоит один или несколько блоков:

```text
<SHiNE:attach;...>
```

клиент трактует их как описания вложений.

После этих блоков идёт обычный пользовательский текст сообщения.

Если технических блоков нет, сообщение считается обычным текстовым сообщением без вложений.

## Формат одного блока вложения

Общий вид:

```text
<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=abcdef...;ar=tx_or_url>
```

Где:

- `attach` — тип технической вставки;
- `v=1` — текущая рабочая версия чернового формата;
- `name` — имя файла;
- `size` — размер файла в байтах;
- `sha256` — SHA-256 файла в hex;
- `ar` — идентификатор файла в архиве или адрес файла в Arweave.

## Несколько вложений

Если к одному сообщению приложено несколько файлов, блоки просто идут подряд в начале текста:

```text
<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=aaa...;ar=...>
<SHiNE:attach;v=1;name=video.mp4;size=5820193;sha256=bbb...;ar=...>
Текст сообщения
```

## Обязательные поля

Для чернового варианта обязательными считаются:

- `v`
- `name`
- `size`
- `sha256`
- `ar`

Если какого-то из этих полей нет, клиент может:

- игнорировать конкретный битый блок;
- не считать его валидным вложением;
- при этом продолжать обрабатывать остальные корректные блоки.

## Почему без `mime` и без `kind`

В минимальном варианте тип файла отдельно не хранится.

Причины:

- это экономит место;
- тип всё равно обычно определяется клиентом;
- для первого варианта достаточно имени файла, адреса, хэша и размера;
- превью и способ отображения клиент может решать сам по расширению имени файла или по попытке открыть файл.

То есть в сообщении не хранится:

- `mime`;
- `kind`;
- `width`;
- `height`;
- `duration`;
- `thumbnail`.

Все эти поля можно добавить позже отдельной версией, если они реально понадобятся.

## Логика клиента

Клиент получает:

- имя файла;
- размер;
- хэш;
- адрес файла.

После этого клиент сам решает, как рендерить вложение:

- если расширение похоже на изображение, можно пробовать показать preview;
- если расширение похоже на видео, можно пробовать встроенный видеоплеер;
- если расширение похоже на аудио, можно пробовать аудиоплеер;
- иначе показывать обычную кнопку скачивания.

Если браузер или клиент не смог показать preview, должен быть fallback на скачивание файла.

## Правила совместимости

- Сообщение без `<SHiNE:attach;...>` остаётся обычным текстом.
- Старые клиенты, которые не умеют распознавать этот формат, могут показывать сообщение как обычный текст целиком.
- Новые клиенты могут скрывать технические блоки и показывать вместо них UI вложений.

## Ограничения чернового варианта

В текущем виде значения полей не предполагают сложного экранирования.

Значит нужно отдельно договориться, как безопасно хранить `name`, если там встретятся символы:

- `;`
- `=`
- `>`

На этапе реальной реализации нужно выбрать один из вариантов:

- жёстко ограничить допустимые символы в `name`;
- хранить имя файла в безопасно закодированном виде;
- добавить отдельное правило escape/encoding.

Пока этот вопрос считается открытым.

## Примеры

### Одно вложение

```text
<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=3f2c8a...;ar=6sYk...>
Привет, вот фото
```

### Два вложения

```text
<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=3f2c8a...;ar=6sYk...>
<SHiNE:attach;v=1;name=report.pdf;size=845221;sha256=9ab01e...;ar=K9Lp...>
Смотри, прикрепил фото и документ
```

## Что надо зафиксировать позже

Перед переводом этого черновика в официальную спецификацию нужно отдельно утвердить:

- точное место этого формата в общей документации блокчейна;
- где именно используются такие вложения: каналы, треды, комментарии или иные текстовые блоки;
- финальные правила кодирования `name`;
- допустим ли полный URL в `ar` или только короткий `txId`;
- нужно ли ограничение на количество вложений в одном сообщении;
- нужна ли отдельная серверная или клиентская проверка расширения файла;
- как именно это будет отображаться в web UI и других клиентах.