Привет,

На днях я потратил 3 дня на попытку мигрирвать свой проект с Hardhat v2.22.19 и Solidity v0.8.28 на Hardhat v3.1.6 и Solidity v0.8.33 (ради transient storage); затем понял, что мажор Hardhat менять не стоит и, если хочется обновиться, то можно обновить минор до v2.28.4; но в итоге всех манипуляций пришел к стандартному выводу: "если работает - не трогай" (*сарказм).

Однако как бы не так. Пока писал этот текст, новые версии библиотек подъехали, некоторые баги исчезли, и приложение ... вдруг заработало. Я в шоке и морально изношен. Поэтому вопрос "мигрировать или не стоит" для меня опять актуален - пересплю с этой идеей.

Вполне возможно, что вы спокойно работаете на последних версиях хардхата и солидити, я "подружился с ними" не с первой попытки. При этом, если вы знаете, где я мог лучше настроить свою систему - буду признателен за комментарии. Ниже - мой путь и костыли, которыми я подпирал свою миграцию.

*заранее приношу свои извинения за смесь англицизмов и russizmov.

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

Это chrome browser extension, которое общается с блокчейном (читает/пишет) через Metamask (точнее, между ними есть еще metamask-extension-provider). Тестирую я это сперва на локальной ноде от хардхата (запускаю в отдельном терминале, из другого накатываю скрипты, потом тестриую из приложения), потом уже в сети Amoy, потом уже в Ethereum. Данную версию своего приложения начинал писать прошлым летом, поэтому у меня используется Hardhat v2.22.19 и Solidity v0.8.28. Хотел было обновиться, чтобы начать использовать transient storage, ~~да вот не получилось. Да и нет критической необходимости в transient.~~ надо снова подумать.

Мой environment - mac, cursor, yarn.

Погнали!

Выбор пути

Есть два стула - 1) сделать апгрейд текущего приложения и его библиотек прямиком из кода приложения, 2) создать с нуля темплейт приложения на нужных библиотеках, перенести туда свой код, и смержить, если надо. Я пошел по второму пути: не фанат версионности библиотек js, когда одни разрабы обновились до последней фичи, а другие нет, и ты сиди и придумывай, как этот зоопарк запустить (даже на текущей задаче, каждый день, когда я начинаю вот этот перенос с нуля, изменяются версии библиотек, и одни баги/варнинги исчезают, другие появляются 🫣).

Инициализируем hardhat v3 проект.

Сначала о версии: почему я хочу hardhat v3.1.6 ради Solidity v0.8.33, если при том же мажоре hardhat v2.28.4, согласно их релизам, они поддерживают нужную версию Солидити уже в hardhat v2.28.2 ? Ответ: нет, не поддерживают. Во-первых, появится варнинг, что "не до конца поддерживают", хоть и скомпилится (если нет transient в коде). Во-вторых, transient упадет в ошибку и не даст скомпилить.

Собственно, открываем курсор (или свою любимую ide) в новой папке, инициализируем новый проект вашим любимым способом. Я буду использовать yarn.

Ставим hardhat: yarn dlx hardhat --init, версию выбираем "Hardhat 3 beta", тип проекта я выбрал "Typescript project using Mocha and Ethers.js", ставим зависимости, yes, yes, yes.

Быстро проверяем, что проект собирается:

yarn
yarn hardhat compile --force
yarn hardhat test
yarn hardhat node

Ничего не падает, тесты зеленые, что-то запускается.

А, нет, простите извините) Чуть не забыл. В версии Solidity 0.8.13 было критическое обновление, и теперь нельзя писать в коде

function myFunc() external {
  assembly {
    ...
  }
}

надо

function myFunc() external {
  assembly ("memory-safe") {
    ...
  }
}

При этом, одна из зависимостей hardhat - forge-std еще не обновлена в шаблоне, поэтому при билде проекта эта зависимость будет выдавать варнинги. Поэтому в package.json надо вручную изменить ее на "forge-std": "foundry-rs/forge-std#v1.14.0"(в версии 1.14.0 уже есть необходимые нам изменения).

Дополнительно, я еще ставлю yarn add -D @solidstate/hardhat-contract-sizer, чтобы видеть размер контрактов. После установки надо добавить этот плагин в hardhat.config.ts, а так же в конфиге можно задать его настройки:

import hardhatContractSizer from '@solidstate/hardhat-contract-sizer'

const config: HardhatUserConfig = {
  plugins: [
    ...,
    hardhatContractSizer
  ],
  solidity: { ... },
  networks: { ... },
  contractSizer: {
    alphaSort: false,
    runOnCompile: false,
    flat: false,
    strict: false,
    only: [],
    except: [],
    unit: 'KiB'
  }
}

При этом, изменились некоторые команды, например команда для просмотра размера контрактов. Все доступные команды можно посмотреть через yarn hardhat --help - собственно, размер теперь посмотреть как yarn hardhat contract-size list . Однако просмотр размера так просто не запустится, будем исправлять ниже.

Настройка HardhatUserConfig

Для начала отмечу, что версии hadrhat 2 и 3 имеют ряд критических несовместимостей. Две из них, которые меня выбесили - это 1) обновленная структура hardhat.config.ts; 2) возможность делать несколько подк��ючений к сетям (пришлось изменять логику скриптов). Если конфиг еще можно с помощью ЧатЖПТ поправить (гуглить тоже пришлось), а вот возможность нескольких подключений заставит вас мыслить иначе при написании скриптов.

Плаг hardhat-contract-sizerмы уже добавили, идем дальше.

Версия Solidity почему-то указана 0.8.28 - меняем на 0.8.33, попутно и в шаблонном контракте меняем:

const config: HardhatUserConfig = {
  plugins: [...],
  solidity: {
    profiles: {
      default: {
        version: "0.8.33"
      },
      production: {
        version: "0.8.33",
        settings: {
          optimizer: {
            enabled: true,
            runs: 200,
          },
        },
      },
    },
  },
  networks: ...

Я вынес конфиг в отдельный объект, мне так проще. Но мы смотрим на секцию solidity.profiles: дефолт и продакшен - это хорошо, однако для hardhat-contract-sizer, который по умолчанию берет настройки из solidity.profiles.default, нужно явно указать settings, даже если выключен оптимизатор, иначе не запустится:

      default: {
        version: "0.8.33",
        settings: {
          optimizer: {
            enabled: false
          },
        },
      },

Вы не поверите, я это только что сам понял, до этого просто копировал старые настройки, тоже работало:

  solidity: {
    version: "0.8.33",
    settings: {
      optimizer: {
        enabled: true,
        runs: 1331,
      },
    },
  },

Теперь надо настроить подключение к сетям. Hardhat теперь имеет два вида сетей: edr-simulated и http. Первые - это локально запускаемые эмуляции сетей, вторая - больше как подключение к какой-то существующей сети (как мейннет, так и локальной едр). Я прям задолбался настраивать это, чтобы у меня был мой список аккаунтов для локальной сети, и чтобы я мог по-человечески это запускать. В итоге:

1) вы по-прежнему можете выбирать сеть при запуске как --network networkName
2) запустить вы можете только edr-simulated сеть
3) по умолчанию, запускается сеть с названием default, и настраивать ее надо тоже через это имя
4) в таком типе сети нельзя задать url для подключения, но можно задать accounts: [ { privateKey: PRIVATE_KEY_1, balance: 100500 } ], и под этими аккаунтами можно будет в ней работать
5) для подключения к сети (локальной или удаленной) надо использовать тип http
6) при подключении надо задать url и нельзя accountsчерез privateKey, но можно через mnemonic

Вот мои настройки для локальной сети и запуска на ней скриптов:

const config: HardhatUserConfig = {
  networks: {
    default: {
      type: "edr-simulated",
      chainType: "l1",
      chainId: 127002,
      accounts: [
        { privateKey: 'PRIVATE_KEY_1', balance: '40200000000000000000000' },
        { privateKey: 'PRIVATE_KEY_2', balance: '40200000000000000000000' },
        { privateKey: 'PRIVATE_KEY_3', balance: '40200000000000000000000' }
      ],
      // mining: {
      //   auto: false,
      //   interval: 5000, // 1 sec
      // }
    },
    localhost: {
      type: "http",
      chainType: "l1",
      url: "http://127.0.0.1:8545",
    },
    amoy: {
      type: "http",
      chainType: "l1",
      chainId: 80002,
      url: "https://rpc-amoy.polygon.technology",
      accounts: [keys.amoy], // not tested yet
    },
    ethereum: {
      type: "http",
      chainType: "l1",
      chainId: 1,
      url: "https://eth.drpc.org",
      accounts: [keys.ethereum], // not tested yet
    },
  },
}

Теперь я могу в одном терминале запустить ноду: yarn hardhat node, а в другом - скрипты на этой ноде: yarn hardhat run scripts/myscript.ts --network localhost

(вообще, не совсем так, но до скриптов мы еще дойдем)

Так же я указываю пути к артефактам и типам (какой-то из путей я не смог перенести, не помню, но код ниже работает). Если будете копировать, то папку compiled надо будет добавить в .gitignore

  paths: {
    sources: './contracts',
    artifacts: './compiled/artifacts',
    cache: './compiled/cache',
    ignition: './ignition',
    tests: './test',
  },
  typechain: {
    outDir: "./compiled/types",
  },

Настройка tsconfig.json

Еще один файл в корне - настройка ts. Поскольку module теперь node16, то надо явно разрешить импорт из json и ts, если у вас оно используется.

{
  "compilerOptions": {
    "lib": ["es2023"],
    "module": "node16",
    "target": "es2022",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "node16",
    "outDir": "dist",

    "allowImportingTsExtensions": true, // эту штуку добавил для импорта ts
    "noEmit": true, // а эта штука нужна, чтобы предыдущая заработала (там есть другая опция, мне эта понравилась больше)

    "resolveJsonModule": true, // эту штуку добавил для импорта js

    "strictNullChecks": false, // этот доп, чт��бы не ругалось на нулл
  }
}

Так-с. Вроде, в корне приложения это все изменения... Можем снова проверить, работают ли основные команды. Удаляем все временные папки, и снова

yarn
yarn hardhat compile --force
yarn hardhat test
yarn hardhat node
yarn hardhat contract-size list
yarn hardhat test --coverage

Ура, работает! Но нет. Однако, это хорошая точка, чтобы закоммитить текущие изменения.
[upd] Во время написания статьи, coverage стал бросать варнинг, что library __HardhatCoverage имеет assembly (:facepalm:)

Переносим смарт контракты

Собственно, можно копировать свои Solidity файлы в папку contracts. При этом, у меня еще используются пара зависимостей от OpenZeppelin, поэтому я их тоже ставлю:

yarn add "@openzeppelin/contracts" "@openzeppelin/contracts-upgradeable"

Помним про assembly ("memory-safe") и обновляем по проекту. Так же устанавливаем версию Solidity на 0.8.33 в смартах. Запускаем наши основные команды (да, я параноик, но именно это иногда спасает). Но в частности, нас интересует yarn hardhat test --coverage - сюрприз, она упадет.

[UPD] не упал. Зуб даю, на днях оно не работало! Суть косяка была проста: когда работает этот coverage, и у вас при этом есть папки и подпапки для смартов, то coverage не создает эти подпапки, а пытается записать в несуществующую папку файл отчетов. Поэтому мне понадобилось попросить у ЧатЖПТ, чтобы пофиксил этот баг, и он создал вот такой скрипт (чуть ниже).

[UPD] В период с 1 на 2 февраля, вышло несколько новых патчей для библиотек - подтверждаю, что на "старых" версиях патчей баг присутствует, на новых - нет. После скрипта укажу эти библиотеки.

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const contractsDir = path.join(__dirname, "../..", "contracts");
const coverageHtmlDir = path.join(__dirname, "../..", "coverage", "html");

function walk(dir, base = "") {
  const items = fs.readdirSync(dir, { withFileTypes: true });

  for (const item of items) {
    if (item.isDirectory()) {
      const rel = path.join(base, item.name);
      const full = path.join(dir, item.name);

      const target = path.join(coverageHtmlDir, rel);
      fs.mkdirSync(target, { recursive: true });

      walk(full, rel);
    }
  }
}

fs.mkdirSync(coverageHtmlDir, { recursive: true });
walk(contractsDir);

console.log("✅ Precreated coverage HTML folders");

и запускался он вот так node scripts/system/makeCoverageDirs.js .

Обновленные библиотеки, которые "исправляют" (наскоро латают) косячное поведение hardhat coverage. При этом, поведение coverage не однозначное: если у вас есть папка contracts, и далее в ней снова папки, и только потом смарты - то coverage создаст стату в папке coverage/html/ и дальше сразу ваши папки из contracts. Если же у вас есть контракт по пути contracts/MyContract.sol, то coverage будет уже в coverage/html/contracts/ 🫣

{
  devDependencies: {
    "@nomicfoundation/hardhat-keystore": "^3.0.4", // ^3.0.2
    "@nomicfoundation/hardhat-typechain": "^3.0.2", // ^3.0.0
    "@nomicfoundation/hardhat-verify": "^3.0.9", // ^3.0.8
    "hardhat": "^3.1.6", // ^3.1.5
  }
}

Проверяем работоспособность и коммитим.

Переносим скрипты

1. Поскольку у нас в tsconfig указано "module": "node16" , то наши импорты должны явно указывать расширение файла, из которого производится импорт, а так же файл index.js, если импорт был раньше "из папки". При этом импорты type должны быть тоже строго type (есть некоторые особенности, но типа рекомендуется все же всегда указывать type):

import { NFTABI } from '../abis.js' // добавлено .js
import type { Signer } from 'ethers'
import type { Test1Facet } from '../../compiled/types/index.js' // + /index.js

2. Раньше был HardhatEthersSigner, теперь это Signer

3. Раньше скрипт мог одновременно импортить функции, а так же запускаться сам, для этого в конце файлов можно было написать:

export async function main() {...}

if (require.main === module) {
	main(MY_CONFIG)
    .then(() => process.exit(0))
	.catch((error) => {
			console.error(error);
			process.exit(1);
	}); 
}

Теперь так нельзя, и надо для таких случаев иметь отдельно файл с экспортами, и отдельно файл для запуска. Зато файл для запуска может прямо в корне делать await:

// файл ./deploy.run.ts

import { main, DEFAULT_CONFIG } from './deploy-system.js'

await main(DEFAULT_CONFIG)

4. Deployment scrtipts. Я не использую Ignition и деплою через ethers, поэтому мой стандартный deployment скрипт выглядел так:

import { ethers } from 'hardhat'
import { MyContract } from '../../compiled/types'

export async function deployMyContract(ownerAddress: string): Promise<MyContract> {
    const Factory = await ethers.getContractFactory('MyContract')
    const instance = await Factory.deploy(ownerAddress)
    await instance.waitForDeployment()
    const deployTx = instance.deploymentTransaction()
    const receipt = await deployTx?.wait()
    console.log(receipt)
    return instance
}

Теперь импортить сеть и получать из нее ethers я должен вот так:

import { network } from 'hardhat'
const { ethers, provider, networkHelpers } = await network.connect()

При этом, при каждом вызове await network.connect(), мы будем иметь новое подключение. Это новая фича hardhat, которая позволяет иметь в коде несколько разных подключений одновременно. Соответственно, для моих целей мне помог singleton, и потом уже импорт ethers и другого из этого singleton, и во все свои deployment функции я теперь первым параметром передаю ethers: HardhatEthers, чтобы работать в рамках одного подключения:

// ethers-singleton.ts
// заба��но, что здесь не ругается на отсутствие /index.js в путях импортов

import { HardhatEthers } from '@nomicfoundation/hardhat-ethers/types'
import { NetworkHelpers } from '@nomicfoundation/hardhat-network-helpers/types'
import { network } from 'hardhat'
import { EthereumProvider } from 'hardhat/types/providers'

let ethersInstance: HardhatEthers | null = null
let providerInstance: EthereumProvider | null = null
let networkHelpersInstance: NetworkHelpers<"generic"> | null = null

/**
 * Gets the singleton ethers instance.
 * Initializes it on first call and reuses the same instance for subsequent calls.
 */
export async function getEthers(): Promise<{ ethers: HardhatEthers, provider: EthereumProvider, networkHelpers: NetworkHelpers<"generic"> }> {
	if (ethersInstance === null) {
		const { ethers, provider, networkHelpers } = await network.connect()
		ethersInstance = ethers
		providerInstance = provider
		networkHelpersInstance = networkHelpers
	}
	return { ethers: ethersInstance, provider: providerInstance, networkHelpers: networkHelpersInstance }
}

// получаем этот ethers как singleton в другом файле

import { getEthers } from '../ethers-singleton.js'
const { ethers, provider, networkHelpers } = await getEthers()

// во все деплой функции добавил `ethers: HardhatEthers` первым параметром

export async function deployMyContract(ethers: HardhatEthers, ownerAddress: string): Promise...

Забегая наперед, кто использовал в тестах loadFixture - теперь она в networkHelpers.loadFixture .

Вроде, со скриптами всё. К сожалению, не могу этот шаг сейчас пройти с вами заново, поскольку у меня много скриптов, и это прям займет время. Поэтому просто сравниваю diff файлов в двух ветках.

Переносим тесты

1. В тестах можно спокойно создавать новое подключение на весь файл, поэтому эта часть упрощается. Потом этот ethers передадите в deployment функции, а loadFixture найдете в networkHelpers.

import { network } from 'hardhat'
const { ethers, provider, networkHelpers } = await network.connect()

2. У меня почему-то изменились папки, в которых лежат артефакты смартов, добавилось /contracts/ как часть пути, просто обновите импорты, не критично.

3. Так же помним об обновлениях для скриптов - оно тут тоже актуально.

4. С бОльшего, это всё. Ниже еще пару импортов (для тестов), на всякий. Мне-то подсказывает Cursor, а вам, может, никто не подсказывает, ха-ха.

import { network } from 'hardhat'
const { ethers, provider, networkHelpers } = await network.connect()
import type { Signer } from 'ethers'
import { EventLog, FunctionFragment, id, Indexed, Interface, keccak256, Log, toUtf8Bytes, ZeroAddress } from 'ethers'
import { HardhatEthers, HardhatEthersProvider } from '@nomicfoundation/hardhat-ethers/types'

Так что же пошло не так?

Уже хотел футер вставить и поздравить себя с окончанием написания данной статьи, однако нет - обновились библиотеки 🤌

Тем не менее, о результатах.

Не понравилось: тесты теперь ранатся больше, чем в 2 раза дольше, чем до обновления. Можно было бы и "потерпеть", да? К тому же, раньше coverage имел более заметные отметки о том, что какую-то строку кода не затронул тестами - сейчас только светло розовый квадратик на белом фоне, вообще не особо заметно. Еще не тестил, как оно подключается к удаленной сети (мейннет / тестнет).

Не баг, а фича, из-за которого я и решил не мигрировать, заодно и статью написать.
[upd] на момент дописания статьи не воспроизводится. Возможно, ночные обновления пакетов исправили это, больше тестировать не буду.

При запуске локальной ноды, запуске на ней скриптов - все работает отлично. Приложение так же корректно читает данные из смартов. Но по какой-то причине, баланс тестового аккаунта при подключении через Метамаск был 0. Соответственно, транзакции из моего приложения не идут, поскольку Метамаск говорит, что деняк нет. При ��том, проверка баланса из скриптов показывала, что баланс есть. Я и кеш метамаска чистил, и заново проходил всю миграцию, и прочее - ничего не помогало. А написал статью - обновились пакеты - и все заработало. Магия 🌈

Вместо окончания

Что ж, как вы уже поняли, мой баг перестал воспроизводиться, поэтому я снова должен подумать, стоит ли переходить на новые версии hardhat и solidity. Но уже не сегодня. 4 часа писал статью, потом обновились библиотеки, еще 4 часа экспериментов... Устал.

Надеюсь, костыли моего переезда помогут кому-нибудь из вас сохранить хоть немного нервных клеток)

О себе

Артем, 37 лет, Козерог, Лилит точно в каком-то доме. Телеграмм канала нет, есть инста, но в ней я "фотограф голых тить" , как сказал один мой товарищ, так что нечего ее здесь палить.

Вообще, я по высшему образованию "математик-программист" (2011), и с 2009 года пишу код за деньги. 11 лет C#, 9 лет JavaScrtipt, и вот уже 5 лет в web3 и Solidity (надеюсь, вы догадаетесь не складывать 11+9+5). Максимум по карьере доходил до Presale Tech Lead, и заработал (я и PM) тогда для нашей компании второй проект от заказчика. Так же мой Solidity marketplace из 60 смартов прошел аудит с 1й попытки. Открыт для новых проектов. Пообщаться можем в телеге (спец телега для таких "реклам", обычно отвечаю быстро, максимум в течение 24 часов). Кота за яйки не тяну - если не сошлись, то не сошлись.

Есть GitHub: artem-bayandin, там чуть больше про меня (на главной странице).
Код в данной статье - из коммерческого проекта, потребуется немного времени, чтобы его адаптировать для масс. Адаптирую, залью, скину ссылку (или запиню в гх). После этого еще планирую опубликовать свой BookingCalendar на Solidity - on-chain календарь для ивентов.

Акк с описанием всех моих проектов в LinkedIn заблокирован из-за рукожопых программистов... Если разблокируют, то будет здесь .

Всё 🤗

Как я мигрировал с Hardhat v2 на v3 и сжёг 1,000,000,000 своих нервных клеток