ESP32 wallet RPC, browser wallet provider, and side panel

2026-06-22 01:30:08 +04:00
parent 475db28095
commit ce2d310e8c
23 changed files with 2407 additions and 300 deletions
@@ -0,0 +1,27 @@
+# ESP32 выбор кошелька и wallet RPC для browser extension
+
+- краткое описание:
+  - в ESP32 заменён домашний блок `баланс + QR` на единый вход в экран кошелька;
+  - добавлен выбор активного кошелька `DeviceKey / RootKey / Custom`;
+  - для browser extension добавлен первый RPC `get_wallet_public_key` через существующий `wallet-session` и `CallSignalToSession`;
+  - в popup расширения добавлен запрос текущего кошелька и копирование `publicKeyBase58`.
+
+- что проверять:
+  - на ESP32 после ввода секрета на главном экране видна кнопка `Кошелёк: ...`;
+  - экран `WALLET` открывается и показывает текущий тип кошелька;
+  - экран `WALLET_SELECT` переключает `DeviceKey`, `RootKey` и `Custom`;
+  - для `Custom` открывается ввод имени и после сохранения derivation работает;
+  - `Показать баланс кошелька` читает баланс именно активного кошелька;
+  - `Показать QR-код кошелька` показывает QR и адрес именно активного кошелька;
+  - browser extension после подключения wallet-session может запросить текущий кошелёк у ESP32;
+  - extension показывает тип кошелька, полный `publicKeyBase58`, результат проверки через PDA и копирует ключ в буфер;
+  - для `dev.key` и `root.key` проверка через PDA даёт ожидаемое совпадение.
+
+- ожидаемый результат:
+  - активный кошелёк на ESP32 реально влияет на баланс, QR и ответ `get_wallet_public_key`;
+  - browser extension получает ответ без ручного ввода `walletSelector`;
+  - homeserver выбирается из опубликованных в PDA sessions и запрос приходит в нужное устройство;
+  - копирование ключа из extension работает.
+
+- статус:
+  - pending
@@ -0,0 +1,18 @@
+# ESP32 English UI and trusted login fix
+
+- Краткое описание:
+  переведён экранный UI ESP32 homeserver на английский язык; добавлена локальная инструкция для AGENTS по ограничению кириллицы; исправлено падение `StartTrustedDeviceLogin`, когда у пользователя ещё нет записи `esp_pairing_settings`.
+
+- Что проверять:
+  1. На ESP32 открыть `HOME`, `WALLET`, `SELECT WALLET`, `WALLET QR` и убедиться, что пользовательские строки на экране только на английском.
+  2. Проверить сценарий выбора `DeviceKey`, `RootKey`, `Custom` и чтение баланса/QR после переключения.
+  3. В расширении открыть popup, запустить `Подключить` для логина, у которого ещё не настраивался trusted-device login.
+  4. Убедиться, что `StartTrustedDeviceLogin` больше не падает с `NullPointerException`.
+  5. После создания pairing-запроса проверить, что homeserver/UI может его увидеть и обработать как раньше.
+
+- Ожидаемый результат:
+  - ESP32 UI читается на устройстве без кириллических строк.
+  - Подключение через trusted-device login стартует без server-side `INTERNAL_HANDLER_ERROR`, даже если настройки pairing ещё ни разу не сохранялись.
+
+- Статус:
+  `pending`
@@ -0,0 +1,20 @@
+# Browser wallet side panel
+
+- Краткое описание:
+  browser extension `SHiNE Wallet` переведён с toolbar popup на штатный Chromium side panel.
+
+- Что проверять:
+  1. Перезагрузить unpacked extension в Chromium-браузере.
+  2. Нажать на иконку `SHiNE Wallet` в toolbar.
+  3. Убедиться, что открывается side panel, а не всплывающий popup.
+  4. Проверить, что панель можно держать открытой при навигации по сайтам.
+  5. Проверить сценарии `Подключить`, `Отключить`, `Обновить устройства`, `Запросить кошелёк`.
+  6. Проверить, что сторона панели управляется браузером, а UI корректно выглядит и слева, и справа.
+
+- Ожидаемый результат:
+  - расширение открывается в штатной боковой панели Chromium;
+  - UI работает так же, как раньше в popup;
+  - панель остаётся доступной как постоянная колонка браузера.
+
+- Статус:
+  `pending`
@@ -0,0 +1,23 @@
+# Wallet provider and ESP sign_transaction
+
+- Краткое описание:
+  browser extension `SHiNE Wallet` теперь внедряет `window.solana` для сайтов и умеет выполнять `connect` и `signTransaction`; подпись транзакции уходит на ESP32 через wallet RPC `sign_transaction`, а подтверждение делается на устройстве.
+
+- Что проверять:
+  1. Перезагрузить unpacked extension в Chromium.
+  2. Открыть сайт/тестовую страницу, которая вызывает `window.solana.connect()`.
+  3. Подтвердить подключение кошелька и убедиться, что сайт получает публичный ключ.
+  4. Открыть сайт/тестовую страницу, которая вызывает `window.solana.signTransaction(...)`.
+  5. Убедиться, что на ESP32 открывается экран `SIGN REQUEST` с комментарием.
+  6. Проверить оба варианта:
+     - `APPROVE` возвращает сайту подписанную транзакцию;
+     - `REJECT` возвращает отказ.
+  7. Проверить сценарии для `DeviceKey`, `RootKey`, `Custom`.
+
+- Ожидаемый результат:
+  - сайт может подключить кошелёк через provider расширения;
+  - транзакция подписывается только после подтверждения на ESP32;
+  - отказ на ESP32 корректно доходит до сайта.
+
+- Статус:
+  `pending`
@@ -110,3 +110,9 @@
 ```text
 sha256$<hex( SHA-256("shine-pairing|" + lower(login.trim()) + "|" + password) )>
 ```
+
+## 8. Связанный документ по внешнему кошельку
+
+Для отдельного RPC-взаимодействия между браузерным wallet-расширением и ESP32 см. документ:
+
+- [Формат_взаимодействия_внешнего_кошелька_и_ESP32.md](/home/ai/work/SHiNE/SHiNE-server-sha256/Dev_Docs/Протоколы/Формат_взаимодействия_внешнего_кошелька_и_ESP32.md)
@@ -0,0 +1,311 @@
+# Формат взаимодействия внешнего кошелька и ESP32
+
+Этот документ фиксирует первый этап формата взаимодействия между внешним браузерным wallet-расширением SHiNE и устройством `ESP32-S3-Touch-AMOLED-2.16`.
+
+Документ описывает:
+
+- как расширение получает текущий активный публичный ключ кошелька с ESP32;
+- как расширение отправляет на ESP32 запрос подписи транзакции;
+- что именно считается активным кошельком на ESP32;
+- какие проверки и UI-реакции ожидаются в браузерном расширении и на устройстве;
+- какие ограничения действуют в текущей версии протокола.
+
+## 1. Общая идея
+
+Устройство ESP32 хранит `master secret` пользователя и локально умеет выводить несколько кошельков из одного секрета.
+
+На устройстве в UI пользователь выбирает текущий активный кошелёк:
+
+- `dev.key`
+- `root.key`
+- `custom`
+
+Для `custom` используется derivation:
+
+```text
+sha256(base64(secret32) + "|wallet." + customName)
+```
+
+Браузерное расширение не указывает ESP32, какой кошелёк нужно вернуть в первом запросе. Оно просто спрашивает:
+
+```text
+какой кошелёк сейчас активен на устройстве
+```
+
+ESP32 возвращает:
+
+- тип текущего активного кошелька;
+- его публичный ключ `Base58`.
+
+## 2. Транспорт и маршрут
+
+Первая версия формата использует уже существующую `wallet-session` браузерного расширения.
+
+Схема маршрута:
+
+`browser extension -> SHiNE server -> homeserver session on ESP32 -> SHiNE server -> browser extension`
+
+В первой версии:
+
+- отдельная цифровая подпись payload не добавляется;
+- отдельное E2E-шифрование для wallet RPC не добавляется;
+- используется существующая авторизованная `wallet-session`, транспорт `WSS` и server-side маршрут через уже существующую операцию `CallSignalToSession`.
+
+## 3. Запрос текущего публичного ключа кошелька
+
+### 3.1. Назначение
+
+Операция нужна, чтобы браузерное расширение могло узнать, какой кошелёк сейчас выбран на ESP32, и показать его пользователю перед дальнейшими действиями.
+
+### 3.2. Формат запроса
+
+```json
+{
+  "v": 1,
+  "operation": "get_wallet_public_key",
+  "requestId": "1718998123456-482193",
+  "timeMs": 1718998123456
+}
+```
+
+### 3.3. Поля запроса
+
+- `v` — версия формата wallet RPC. Для текущего варианта: `1`.
+- `operation` — строка операции. Для текущего запроса: `get_wallet_public_key`.
+- `requestId` — идентификатор запроса, уникальный в пределах сеанса расширения. Рекомендуемый формат:
+  `timeMs-random`.
+- `timeMs` — локальное время отправителя в миллисекундах.
+
+### 3.4. Поведение ESP32
+
+При получении такого запроса ESP32:
+
+1. смотрит, какой кошелёк сейчас выбран в локальном UI;
+2. вычисляет или берёт уже подготовленный публичный ключ именно этого активного кошелька;
+3. возвращает тип кошелька и его `publicKeyBase58`.
+
+Запрос не содержит:
+
+- `walletSelector`;
+- `customName`;
+- `targetSessionName`.
+
+Они намеренно не входят в первую версию этого запроса.
+
+## 4. Формат ответа
+
+```json
+{
+  "v": 1,
+  "op": "get_wallet_public_key_result",
+  "requestId": "1718998123456-482193",
+  "ok": true,
+  "wallet": {
+    "type": "custom",
+    "publicKeyBase58": "...."
+  },
+  "timeMs": 1718998123999
+}
+```
+
+## 5. Поля ответа
+
+- `v` — версия формата ответа. Сейчас `1`.
+- `op` — строка результата операции. Сейчас `get_wallet_public_key_result`.
+- `requestId` — должен совпадать с `requestId` исходного запроса.
+- `ok` — признак успешного результата.
+- `wallet.type` — тип активного кошелька:
+  - `dev.key`
+  - `root.key`
+  - `custom`
+- `wallet.publicKeyBase58` — публичный ключ активного кошелька в `Base58`.
+- `timeMs` — время формирования ответа на стороне ESP32 в миллисекундах.
+
+## 6. Ошибки первой версии
+
+Минимальный формат ошибки в первой версии допускается таким:
+
+```json
+{
+  "v": 1,
+  "op": "get_wallet_public_key_result",
+  "requestId": "1718998123456-482193",
+  "ok": false,
+  "error": "wallet_unavailable",
+  "timeMs": 1718998123999
+}
+```
+
+Рекомендуемые коды ошибок первой версии:
+
+- `wallet_unavailable` — на устройстве нельзя получить текущий кошелёк;
+- `secret_not_configured` — на устройстве ещё нет корректно сохранённого секрета;
+- `wallet_type_unknown` — выбранный локальный тип кошелька не распознан;
+- `internal_error` — прочая локальная ошибка устройства.
+
+## 7. Правила для браузерного расширения
+
+После ответа `ok=true` расширение должно:
+
+1. показать пользователю тип кошелька;
+2. показать полный `publicKeyBase58`;
+3. дать кнопку копирования ключа в буфер;
+4. сохранить этот ключ как текущий ключ устройства для следующей операции подписи.
+
+### 7.1. Проверка через PDA Solana
+
+Расширение уже знает публичные ключи пользователя из Solana PDA. Поэтому оно может дополнительно проверить ответ ESP32:
+
+- если `wallet.type = dev.key`, то `publicKeyBase58` должен совпасть с `deviceKey`, прочитанным из PDA;
+- если `wallet.type = root.key`, то `publicKeyBase58` должен совпасть с `rootKey`, прочитанным из PDA;
+- если `wallet.type = custom`, такой проверки по PDA в первой версии нет.
+
+При несовпадении для `dev.key` или `root.key` расширение должно показать пользователю предупреждение, что возвращённый ключ не совпал с ожидаемым ключом из PDA.
+
+## 8. Ожидаемое поведение UI расширения
+
+### 8.1. Общий вид popup
+
+Popup браузерного расширения должен быть узким и вытянутым по вертикали.
+
+### 8.2. Состояние без подключения
+
+Если `wallet-session` ещё не подключена:
+
+- показывается кнопка `Подключить`;
+- по нажатию открывается экран подключения, близкий по смыслу к сценарию `Войти через другое устройство`;
+- пользователь вводит логин устройства и получает код подключения.
+
+### 8.3. Состояние после подключения
+
+Если `wallet-session` уже подключена:
+
+- показывается статус `Подключено`;
+- остаётся выбор homeserver;
+- появляется кнопка запроса текущего кошелька;
+- появляется кнопка `Отключить`.
+
+### 8.4. Подключение кошелька с сайта
+
+Когда сайт просит подключить кошелёк через расширение, расширение должно вести себя как обычный wallet extension:
+
+1. показать пользователю подтверждение подключения;
+2. показать, какой именно кошелёк будет подключён;
+3. после подтверждения пользователя завершить подключение;
+4. если пользователь отказался, не подключать кошелёк к сайту.
+
+## 9. Запрос подписи транзакции
+
+### 9.1. Назначение
+
+Операция нужна, чтобы браузерное расширение могло запросить у ESP32 подпись Solana-транзакции текущим активным кошельком.
+
+Расширение передаёт:
+
+- публичный ключ, которым ожидается подпись;
+- сериализованную транзакцию;
+- комментарий, который должен быть показан на экране ESP32.
+
+ESP32:
+
+1. показывает пользователю запрос подтверждения;
+2. показывает комментарий к подписи;
+3. после нажатия `APPROVE` или `REJECT` возвращает ответ в расширение.
+
+### 9.2. Формат запроса
+
+```json
+{
+  "v": 1,
+  "operation": "sign_transaction",
+  "requestId": "1718998123456-482193",
+  "timeMs": 1718998123456,
+  "publicKeyBase58": "....",
+  "transactionBase64": "....",
+  "comment": "Site https://example.com requested transaction signature"
+}
+```
+
+### 9.3. Поля запроса
+
+- `v` — версия wallet RPC. Сейчас `1`.
+- `operation` — строка операции: `sign_transaction`.
+- `requestId` — идентификатор запроса.
+- `timeMs` — время отправки на стороне расширения.
+- `publicKeyBase58` — публичный ключ, от которого ожидается подпись.
+- `transactionBase64` — сериализованная Solana transaction в `base64`.
+- `comment` — короткое текстовое описание, которое ESP32 показывает пользователю при запросе подписи.
+
+### 9.4. Поведение ESP32
+
+При получении такого запроса ESP32:
+
+1. сравнивает `publicKeyBase58` с публичным ключом текущего активного выбранного кошелька;
+2. если ключ не совпадает, сразу возвращает ошибку `wallet_mismatch`;
+3. если ключ совпадает, показывает отдельный экран подтверждения подписи;
+4. на экране показывает:
+   - каким кошельком будет выполнена подпись;
+   - комментарий `comment`;
+   - кнопки `APPROVE` и `REJECT`;
+5. если пользователь подтверждает подпись, ESP32 подписывает транзакцию и возвращает результат;
+6. если пользователь отклоняет, ESP32 возвращает `rejected_by_user`.
+
+## 10. Формат ответа на подпись
+
+```json
+{
+  "v": 1,
+  "op": "sign_transaction_result",
+  "requestId": "1718998123456-482193",
+  "ok": true,
+  "publicKeyBase58": "....",
+  "signatureBase58": "....",
+  "signedTransactionBase64": "....",
+  "timeMs": 1718998123999
+}
+```
+
+Если пользователь отклонил запрос:
+
+```json
+{
+  "v": 1,
+  "op": "sign_transaction_result",
+  "requestId": "1718998123456-482193",
+  "ok": false,
+  "error": "rejected_by_user",
+  "timeMs": 1718998123999
+}
+```
+
+Рекомендуемые ошибки для `sign_transaction`:
+
+- `rejected_by_user`
+- `wallet_unavailable`
+- `wallet_mismatch`
+- `transaction_base64_invalid`
+- `transaction_sign_failed`
+- `bad_request`
+
+## 11. Подключение кошелька с сайта
+
+При вызове сайта `connect wallet` расширение должно вести себя как обычный wallet extension:
+
+1. запросить подтверждение у пользователя в браузере;
+2. получить текущий публичный ключ с ESP32;
+3. вернуть сайту `publicKey` текущего активного кошелька.
+
+Для `signTransaction` расширение:
+
+1. получает транзакцию от сайта;
+2. пересылает её на ESP32 через `sign_transaction`;
+3. ждёт решение пользователя на устройстве;
+4. возвращает браузеру уже подписанную транзакцию.
+
+## 12. Ограничения текущей версии
+
+- запрос возвращает только текущий активный кошелёк, а не список всех кошельков;
+- выбор типа кошелька делается только на самом ESP32;
+- отдельная цифровая подпись ответа пока не используется;
+- отдельное E2E-шифрование wallet RPC пока не используется;
+- `custom`-кошельки в первой версии не сверяются с PDA.