# ZHCASH Experimental Upgrade README, 2026-07-20

Этот документ описывает экспериментальную Linux x86_64 maintenance-сборку:

- Скачать: `http://95.133.236.37:8080/experimental/linux-x86_64/zhcash-linux-x86_64-experimental-20260720.tar.gz`
- SHA256: `58f305d0be50a59ffc9a2b67c780e2816ed160d2b02d09fd7e04fc617258d018`
- В составе: `zerohourd`, `zerohour-cli`, `zerohour-qt`, `zerohour-tx`, `zerohour-wallet`

Сборка экспериментальная. Она предназначена для проверки совместимости перед публичным maintenance-релизом.

## Что Было Сделано

Апгрейд сохраняет существующее поведение сети, протокола и консенсуса. Намеренно изменялись только wallet/RPC/Qt, локальная симуляция, диагностика и тестовая инфраструктура.

Изменения:

- `sendtoaddress` теперь определяет, что адрес назначения является существующим contract address, и формирует стандартный `OP_CALL` с пустым calldata и отправляемой суммой ZHC. Это должно вызывать Solidity `receive() external payable` или payable fallback.
- В Qt `sendtocontract` больше не зануляет amount для ABI-функций, помеченных как non-payable. Если пользователь указывает ненулевую сумму для non-payable функции, Qt показывает предупреждение.
- Исправлена обработка gas в `callcontract` для локальной симуляции. Теперь можно использовать gas выше `DEFAULT_BLOCK_GAS_LIMIT_DGP` до настроенного максимума.
- Добавлен RPC-параметр `-rpcmaxcallcontractgas=<n>`. По умолчанию `1000000000`, с ограничением `MAX_BLOCK_GAS_LIMIT_DGP`. Влияет только на локальную симуляцию `callcontract`.
- Явно отрицательные или нулевые значения gas отклоняются в RPC-путях, где gas передается пользователем.
- `createrawtransaction` в maintenance-режиме отклоняет создание транзакции с несколькими contract outputs. Исполнение исторических блоков не меняется.
- Добавлена диагностика медленной валидации:
  - `-zhcslowblockms=<n>`
  - `-zhcslowevmms=<n>`
  - `-zhcslowcommitms=<n>`
- Исправлен свежий запуск `regtest`: настроенный genesis hash принимается при header proof checks.
- Добавлены compatibility shims для ZHCASH functional tests.

## Что Не Менялось

Эти области должны остаться совместимыми со старыми нодами и историческими данными:

- P2P-протокол
- формат блока
- формат транзакций, принимаемых консенсусом
- правила исторического EVM execution
- поведение `ZHCASHTxConverter` для старых блоков
- расчет state root для исторических блоков
- формат шифрования wallet
- Berkeley DB формат `wallet.dat`
- OpenSSL wallet cryptography path: SHA512 плюс AES-256-CBC остается без изменений

В maintenance-линии запрещены изменения консенсуса, кроме отдельно рассмотренного патча халвинга/tail reward.

## Чеклист Апгрейда

Перед заменой production-ноды:

1. Чисто остановить старую ноду:

   ```bash
   zerohour-cli stop
   ```

2. Сделать backup всего datadir, особенно `wallet.dat`:

   ```bash
   cp -a ~/.zerohour ~/.zerohour.backup-before-20260720
   ```

3. Проверить скачанный архив:

   ```bash
   sha256sum zhcash-linux-x86_64-experimental-20260720.tar.gz
   ```

   Ожидаемое значение:

   ```text
   58f305d0be50a59ffc9a2b67c780e2816ed160d2b02d09fd7e04fc617258d018
   ```

4. Распаковать и проверить версии:

   ```bash
   tar -xzf zhcash-linux-x86_64-experimental-20260720.tar.gz
   ./zhcash-linux-x86_64-experimental-20260720/bin/zerohourd --version
   ./zhcash-linux-x86_64-experimental-20260720/bin/zerohour-qt --version
   ```

5. Запустить ноду с логированием медленной валидации:

   ```bash
   ./zhcash-linux-x86_64-experimental-20260720/bin/zerohourd \
     -daemon \
     -zhcslowblockms=2000 \
     -zhcslowevmms=1000 \
     -zhcslowcommitms=1000
   ```

## Что Нужно Проверить Для Совместимости

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

### Проверки Wallet

- Старый `wallet.dat` открывается без ошибок.
- Зашифрованный wallet разблокируется старым passphrase.
- Старые адреса видны.
- Баланс совпадает со старой нодой.
- `listunspent` возвращает ожидаемые UTXO.
- Небольшой обычный `sendtoaddress` на обычный адрес работает.
- Wallet можно остановить и заново открыть без повреждения.

Команды:

```bash
zerohour-cli getwalletinfo
zerohour-cli getbalance
zerohour-cli listunspent
zerohour-cli walletpassphrase "passphrase" 60
```

### Проверки Chain И Sync

- Нода стартует на существующем datadir без reindex, если reindex явно не запрошен.
- Best block hash совпадает с доверенной старой нодой на той же высоте.
- Нода может синхронизироваться дальше 10,000 блоков.
- Нода чисто останавливается после синхронизации.
- После повторного запуска нет ошибок block database.

Команды:

```bash
zerohour-cli getblockchaininfo
zerohour-cli getbestblockhash
zerohour-cli getblockcount
zerohour-cli stop
```

### Проверки Peer Compatibility

- Нода подключается к старым публичным нодам.
- Старые ноды не отключают новую ноду из-за несовпадения протокола.
- `getpeerinfo` показывает нормальный inbound/outbound traffic.
- Блоки, принимаемые старой нодой, принимаются новой нодой.

Команды:

```bash
zerohour-cli getnetworkinfo
zerohour-cli getpeerinfo
zerohour-cli addnode "193.24.208.96:38100" "onetry"
```

### Проверки Smart Contracts

- Существующие контракты читаются через `callcontract`.
- Сложный `callcontract`, который раньше упирался в Default gas, выполняется с большим gas.
- `callcontract` не тратит монеты и не создает on-chain state changes.
- `sendtocontract` с amount работает для payable functions.
- Обычный `sendtoaddress` на существующий contract address создает `OP_CALL` и вызывает payable `receive()` или fallback.
- Обычный `sendtoaddress` на обычный адрес остается обычным платежом.
- Создание raw transaction с несколькими contract outputs отклоняется в maintenance-режиме.

Пример:

```bash
zerohour-cli callcontract <contract> <datahex> "" 100000000
zerohour-cli sendtoaddress <normal_address> 1
zerohour-cli sendtoaddress <contract_address> 1
```

### Проверки Qt

- `zerohour-qt` запускается на Ubuntu 24.04 при наличии нужных X11 runtime libraries.
- Wallet открывается и показывает ожидаемый баланс.
- Форма отправки работает для обычных платежей.
- В SendToContract поле amount остается активным.
- Non-payable ABI плюс ненулевая сумма показывает предупреждение, а не молча зануляет amount.

### Проверки Производительности

- Во время initial sync UI или daemon logs должны показывать прогресс, а не выглядеть как постоянное зависание.
- В `debug.log` нужно смотреть строки медленной валидации:

  ```text
  Slow block validation
  Slow EVM execution
  ```

- Если зависания остаются, нужно зафиксировать:
  - block height
  - block hash
  - последние 200 строк `debug.log`
  - операционную систему
  - использовался Qt или daemon

## Rollback

Откат должен сохранять backup старого datadir.

1. Остановить экспериментальную ноду:

   ```bash
   zerohour-cli stop
   ```

2. Восстановить backup:

   ```bash
   mv ~/.zerohour ~/.zerohour.experimental-failed
   mv ~/.zerohour.backup-before-20260720 ~/.zerohour
   ```

3. Запустить предыдущий проверенный binary.

Не стоит использовать datadir, измененный экспериментальной нодой, со старым binary без backup и теста rollback.

## Что Уже Проверено На Build-Машине

- Linux CLI и Qt binaries успешно скомпилированы.
- `zerohourd --version` работает.
- `zerohour-qt --version` работает под `xvfb`.
- `ldd zerohour-qt` не показывает missing shared libraries.
- Fresh `regtest` стартует и отвечает на `getblockchaininfo`.
- `test/functional/qtum_callcontract.py` проходит.
- `make check` завершается успешно, но текущий configure генерирует zero unit tests.

Что еще обязательно проверить:

- реальную mainnet/testnet sync со старыми нодами;
- разблокировку старого зашифрованного `wallet.dat` на пользовательских wallet;
- receive/fallback test на известном deployed contract;
- Windows и macOS packaging checks отдельно, вне этой Linux-only экспериментальной сборки.