# IBC v2 і шардинг

> IBC v2 у NeuroChain — постквантові заголовки комітів, перекази токенів у стилі ICS-20 з ескроу й ваучерами, атестації VMGuardian як пакети, налаштування релеєра й операторів, конфігурація, поточний стан і як це тестується; плюс робота з шардами.

Source: https://docs.nro.world/uk/operate/ibc

## IBC v2 <Badge type="warning" text="експериментально" /> {#ibc-v2}

NeuroChain з'єднується з іншими мережами через **IBC v2** — спрощену, орієнтовану на клієнтів версію протоколу Inter-Blockchain Communication (відому також як *Eureka*). Перший контрагент — екосистема Cosmos, починаючи з Neutron (CosmWasm).

NeuroChain додає **постквантову сумісність**: її коміти підписуються ML-DSA-65, тож легкий клієнт контрагента перевіряє NeuroChain постквантовим підписом замість схем ECDSA / Ed25519, на які спирається класичний IBC.

### Що передається каналом

| Пакет | Формат | Призначення |
|-------|--------|-------------|
| Взаємозамінний переказ | `nc-ics20-v1|denom|amount|sender|receiver|channel|memo` | Переміщення NRO чи ваучерів між мережами в стилі ICS-20 |
| Атестація безпеки | `nc-ibc-attest-v1|bytecode_hash|score|model|timestamp|subject` | Передача оцінки [VMGuardian](/uk/ai/vmguardian) в іншу мережу |
| Заголовок коміту | `nc-pq-lc-v1|chain_id|height|block_hash|state_root`, підписаний ML-DSA-65 | Те, що перевіряє легкий клієнт контрагента |

Пакет атестації — місце, де сходяться дві головні ставки: доказ безпеки від AI, створений у NeuroChain, на який може покластися інша мережа.

### Перекази токенів

![Переказ IBC v2: користувач підписує ibc_transfer; валідатори блокують NRO в ескроу каналу; кожні 1 000 блоків вони підписують заголовок коміту; релеєр отримує заголовок, оновлює клієнт контрагента й доставляє пакет; контрагент випускає ваучер; релеєр підтверджує, і ескроу спалюється; без підтвердження до тайм-ауту відправнику повертаються кошти](/diagrams/uk/ibc-v2-transfer.svg)

**Вихідні (NeuroChain → контрагент)**

1. `POST /api/v1/ibc/transfer` блокує суму на ескроу-акаунті каналу `neuro:ibc.escrow.<channel>`; пакет — `locked`.
2. Релеєр доставляє його; контрагент випускає ваучер.
3. `POST /api/v1/ibc/ack` позначає його `committed` і спалює ескроу.
4. Немає підтвердження до тайм-ауту → відправнику автоматично повертаються кошти.

**Вхідні (контрагент → NeuroChain)**

1. Релеєр надсилає `POST /api/v1/ibc/recv` з пакетом і його зобов'язанням (commitment).
2. Отримувачу зараховується **IBC-ваучер** з denom `ibc/<SHA-256 шляху трасування>`, як в ibc-go. Пакет з певним id можна отримати лише раз.
3. `POST /api/v1/ibc/redeem` спалює ваучер і надсилає актив назад через канал.

Суми в пакетах — цілі числа в базовому denom (`unro` для NRO).

### Хто що підписує

| Операція | Хто може надіслати | Підпис |
|----------|--------------------|--------|
| `transfer`, `redeem` | Будь-який акаунт, для власних коштів | Покриває кожне поле — отримувача, канал, мережу, denom, суму |
| `recv`, `ack`, `channel/open`, `channel/pause`, `client/update`, `attest` | Лише **оператори IBC**: ключі з `NEUROCHAIN_IBC_OPERATOR_PUBKEYS` | Так само, ключем оператора |

Повноваження дає **публічний ключ** оператора, а не заявлена адреса. Усі операції IBC застосовуються в консенсусі й підписуються для `neuro:system.ibc`.

### Поточний стан і обмеження

| Частина | Стан |
|---------|------|
| Ескроу, ваучери, трасування denom, тайм-аути, записи пакетів | Реалізовано в ноді, покрито модульними тестами |
| Постквантові заголовки комітів, що підписуються кожні 1 000 блоків | Реалізовано; доступні за `GET /api/v1/ibc/header/latest` |
| Підписи, що прив'язують поля кожної операції IBC | Реалізовано, з еталонними тестовими векторами |
| Контракт контрагента `neuro-pq-client` (CosmWasm) | Зібрано (`neurochain/contracts/neuro_pq_client`). **Ще не бездовірчий:** перевіряє довірений ключ релеєра і зростання висоти; підпис ML-DSA-65 перевіряє релеєр поза мережею |
| Вхідні пакети | Приймаються від операторів IBC із зобов'язанням над полями зарахування; доказ членства Меркла від контрагента запропоновано, але не реалізовано |
| Наскрізний переказ з тестовою мережею Neutron | **Ще не виконано** — скрипт розгортання готовий (`tools/ibc-relayer/deploy_neutron.js`), потрібен поповнений акаунт у тестовій мережі |
| Повне рукостискання IBC v2 з ibc-go | Заплановано |

Доки контрагент не перевіряє ML-DSA-65 у мережі, канал IBC довіряє своєму релеєру. Тримайте `NEUROCHAIN_IBC_MAX_PACKET_UNRO` і `NEUROCHAIN_IBC_MAX_CHANNEL_ESCROW_UNRO` низькими в будь-якій мережі зі справжньою вартістю.

**Як це тестується:** модульні тести ноди покривають блокування, підтвердження, повернення за тайм-аутом, зарахування й погашення ваучерів, дублікати пакетів, зарезервовані id пакетів, розбіжності зобов'язань, повноваження операторів і канонічні підписані повідомлення (`cargo test -p neurochain-node ibc`). `GET /api/v1/ibc/pq/test-vector` повертає фіксовані заголовок, ключ і підпис, щоб реалізація контрагента могла перевірити, що кодує й перевіряє ті самі байти.

### Запуск релеєра (лабораторія)

```bash
# 1. Запустіть ноду з дозволеним ключем оператора
NEUROCHAIN_IBC_OPERATOR_PUBKEYS=<публічний ключ ML-DSA-65 оператора, hex> ./target/debug/neurochain

# 2. Відкрийте канал (підписує оператор)
#    POST /api/v1/ibc/channel/open  { from, channel, port, counterparty_chain, allowed_denoms, … }

# 3. Після контрольної точки експортуйте заголовок для клієнта контрагента
NODE_RPC=http://localhost:9933 node neurochain/tools/ibc-relayer/export_update_client.js
```

Скрипт виводить повідомлення `UpdateClient` для `neuro-pq-client`. Поля запитів для кожного ендпоінта IBC — у [довіднику REST](/uk/reference/rest#ibc-v2).

### Конфігурація {#configuration}

| Змінна | За замовчуванням | Значення |
|--------|------------------|----------|
| `NEUROCHAIN_IBC_OPERATOR_PUBKEYS` | порожньо | Публічні ключі через кому, яким дозволено релеїти й адмініструвати канали |
| `NEUROCHAIN_IBC_TRUSTED_PUBKEYS` | порожньо | Ключі ML-DSA-65, чиї підписи заголовків приймаються для вхідних пакетів; порожньо — приймається будь-який дійсний підпис (лише лабораторія) |
| `NEUROCHAIN_IBC_REQUIRE_HEADER` | у mainnet | Вхідні пакети мають супроводжуватися перевіреним заголовком |
| `NEUROCHAIN_IBC_REQUIRE_PACKET_COMMITMENT` | у mainnet | Вхідні пакети мають нести зобов'язання над своїми полями |
| `NEUROCHAIN_IBC_TIMEOUT_BLOCKS` | 10 | Блоків, після яких непідтверджений вихідний пакет повертається |
| `NEUROCHAIN_IBC_MAX_PACKET_UNRO` | без ліміту | Найбільший одиничний переказ |
| `NEUROCHAIN_IBC_MAX_CHANNEL_ESCROW_UNRO` | без ліміту | Найбільше, що один канал може тримати в ескроу |
| `NEUROCHAIN_IBC_NATIVE_DENOM` | `unro` | Базовий denom NRO в пакетах |

## Шардинг <Badge type="warning" text="експериментально" /> {#sharding}

Кожен шард запускає власний екземпляр консенсусу зі своїми валідаторами й висотою; акаунти належать шарду `FNV-1a(address) mod n_shards`. Як урегульовуються міжшардові перекази, описано в [Консенсус → Шардинг](/uk/learn/consensus#sharding).

Запускайте одну ноду на шард:

```bash
NEUROCHAIN_SHARDS=4 NEUROCHAIN_SHARD_ID=0 NEUROCHAIN_DATA_DIR=./data-s0 NEUROCHAIN_RPC_PORT=9933 … ./target/debug/neurochain
NEUROCHAIN_SHARDS=4 NEUROCHAIN_SHARD_ID=1 NEUROCHAIN_DATA_DIR=./data-s1 NEUROCHAIN_RPC_PORT=9934 … ./target/debug/neurochain
```

- Без `NEUROCHAIN_SHARD_ID` нода працює з одним шардом і не створює міжшардових переказів.
- Gateway маршрутизує кожну транзакцію до ноди шарда відправника.
- Стежте за передачами через `GET /api/v1/cross-shard/queue?status=locked`, а за висотами шардів — через `GET /api/v1/shards`.

Усередині міжшардові передачі використовують той самий пакетний рушій, що й IBC v2 — шард є одним видом кінця каналу, зовнішня мережа — іншим.