Руководство по инструментарию для разработки Flow

Обзор

В этой статье будут рассмотрены различные инструменты и технологии, которые вы можете использовать для создания на блокчейне Flow. Поскольку статья посвящена инструментам, мы предполагаем, что вы уже имеете базовое представление о Cadence. Если нет, приглашаем вас пройти обучение на сайте Cadence https://developers.flow.com/cadence/tutorial/01-first-steps

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

• Язык программирования Cadence
• Публичные приватные ключи
• Блокчейн Flow

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

Цель данного руководства - ознакомить вас с процессом Flow, то есть с тем, какие инструменты вам понадобятся и какие шаги необходимо предпринять, начиная с локальной разработки приложения и заканчивая его производственным развертыванием в Mainnet.

⏱️ Время чтения - около 30 минут, так что сделайте себе кофе прямо сейчас и следите за развитием событий.

1-минутное введение в Flow

Я быстро познакомлю вас с самыми основами Flow через призму разработчиков, поэтому не стесняйтесь пропустить это, если вы знаете, как работает Flow.

Flow - это децентрализованный блокчейн, представляющий новый подход к масштабированию за счет наличия нескольких одноцелевых узлов (узел исполнения, узел сбора, узел доступа и т.д.). Нас интересует именно узел доступа, поскольку он дает нам возможность получить доступ к сети Flow, подключившись к ее API, но не беспокойтесь: у нас есть библиотеки, облегчающие общение с узлом.

Общаясь с узлом доступа, мы можем отправлять новые транзакции, выполнять скрипты и получать информацию о блокчейне, такую как блоки, транзакции и т. д. Подробнее о том, как работает Flow, можно прочитать здесь, но для данного руководства эти знания необязательны. Взаимодействие с Flow возможно путем отправки транзакций, содержащих код Cadence, вызывающий любой контракт и мутирующий блокчейн Flow. Считайте их "операциями записи". Если вам нужно только запросить или "прочитать" блокчейн, вы можете использовать скрипты, которые опять же могут содержать любой код Cadence, но никак не изменяют сеть Flow, а возвращают интересующую нас информацию, например, вызывают функции контракта.

Flow также представила свой язык программирования под названием Cadence. Cadence - отличный язык для блокчейна, поскольку он ориентирован на ресурсы, что гарантирует, что ресурсы (определенный тип) могут существовать только в одном месте в одно время, не могут быть скопированы, а также не могут быть случайно потеряны или удалены. Полное руководство по языку Cadence можно найти здесь, но некоторые основы мы рассмотрим позже, когда будем писать контракты.

Еще одно уникальное свойство языка Flow, которое делает его замечательным, - это уникальная модель проектирования счетов. Аккаунты не просто представлены адресами, которые получены из закрытых ключей (как, например, в Ethereum), это реальные сущности, которые живут в сети Flow, то есть вы можете создать новый аккаунт в сети, вызвав функцию и назначив ему любой ключ, вы даже можете полностью изменить ключи, а также удалить их, после чего аккаунт становится доступным только для чтения.

Аккаунты дают вам больше полномочий по делегированию доступа по сравнению с другими сетями. Аккаунт имеет свое хранилище, где вы можете очень дешево хранить любые данные (в настоящее время 1 МБ за 0,01 Flow). Подробнее о ключевых компонентах Flow вы можете прочитать здесь.

Flow даже представляет способ бескошелькового онбординга, что является темой другой статьи.

В настоящее время существует несколько сетей Flow для различных целей. Вы можете получить доступ к этим сетям через API узлов доступа (в настоящее время это API gRPC и HTTP, но не беспокойтесь об этом, так как SDK поддерживают их). API доступны по разным адресам:

• Emulator APIs [localhost:3569](<http://localhost:3569>) - локальный запуск сети Flow с помощью инструмента эмулятора.
• Testnet APIs [access.devnet.nodes.onflow.org:9000](<http://access.devnet.nodes.onflow.org:9000>) - testnet используется для тестирования вашего приложения, аналогично тому, как staging используется в web2 world,****.
• Mainnet APIs [access.mainnet.nodes.onflow.org:9000](<http://access.mainnet.nodes.onflow.org:9000>) - mainnet - это производственная сеть Flow****.

Инструменты и технологии для работы с Flow

Доступ к Building on Flow можно получить с помощью различных технологий, которые мы предоставляем, поэтому мы рассмотрим некоторые из наиболее распространенных, но имейте в виду, что вы можете свободно выбрать и другие.

JS FCL

При написании приложения javascript мы можем использовать JS FCL SDK, просто Flow javascript SDK. Это позволяет нам взаимодействовать с сетью Flow, отправляя транзакции, выполняя сценарии, читая блоки и события и многое другое. Тем не менее, поскольку большинство приложений хотят отправлять транзакции для изменения данных блокчейна Flow, они должны каким-то образом подписывать эти транзакции. Если вы пришли из Ethereum, вы знаете, что эта проблема была решена с помощью других кошельков, таких как Metamask on Flow, однако мы нашли лучшее решение, и оно уже встроено в FCL SDK для вас. SDK знает, как подключиться к доступным поставщикам кошельков, и просит пользователя подтвердить подписание транзакции с помощью модального окна, которое вы видели ранее в демонстрации. Это возможно с помощью протокола обнаружения кошелька, и вы можете прочитать об этом здесь., но пока вам не нужно слишком беспокоиться об этом; думайте об этом как об OAuth для Flow.

Конечно, чтобы пользователи могли войти в систему, у них должен быть существующий кошелек с выбранным провайдером. Как объяснено ниже, мы смоделировали этого поставщика кошелька во время разработки с помощью кошелька для разработчиков. Полный справочник FCL можно найти здесь . Таким образом, если вы создаете интерфейс для своего dApp, вам нужен FCL для взаимодействия с кошельками и Flow. Ниже приведена краткая схема того, как FCL SDK взаимодействует со всеми другими инструментами, такими как кошелек разработчика и эмулятор.

‍

‍

CLI

Flow CLI — это швейцарский армейский нож при работе с Flow. Он предлагает команды для отправки транзакций, выполнения сценариев и получения блоков, а также включает в себя другие инструменты, такие как эмулятор Flow, кошелек для разработчиков и Flowser. Он предоставляет инструменты разработки, которые следят за вашими контрактами и автоматически обновляют их во время разработки. Он также знает, как разрешать импорт других контрактов и многие другие интересные функции, которые вам понадобятся в процессе разработки.

Вот краткий обзор экрана справки:

‍

Flow.json

Файл flow.json содержит конфигурацию вашего проекта. Там мы определяем контракты, которые мы будем развертывать, учетные записи, которые мы создали в сети, и различные сети, к которым мы можем получить доступ. Flow.json используется другими инструментами и библиотеками (такими как FCL) и является связующим звеном между потребителями. Подробнее о flow.json можно прочитать здесь .

Пример файла flow.json:

‍

Эмулятор Flow

Эмулятор Flow — это инструмент, который запускает простую версию сети Flow на вашем локальном компьютере и может использоваться для разработки. Он предоставляет те же API-интерфейсы узла доступа в основной сети Flow. Вы можете быстро запустить эмулятор Flow через интерфейс командной строки Flow, выполнив команду эмулятора Flow. Эмулятор предоставляет вывод, в котором вы можете увидеть транзакции, которые он выполняет, и различные журналы.

‍

Кошелек для разработчиков

Кошелек Dev — это инструмент, который локально эмулирует FCL-совместимый кошелек. Он реализует определенные API-интерфейсы, необходимые FCL для связи с ним и подписания транзакций. Кошелек разработчика автоматически создает кошелек, который вы можете использовать во время разработки. На данный момент вы можете думать об этом как о инструменте «черный ящик», который позволяет вам подписывать любую транзакцию, как это сделал бы пользователь при развертывании в рабочей среде. Конечно, в производстве кошелек разработчика будет заменен любыми поставщиками производственных кошельков, такими как кошелек Blocto или Lilico.

‍

Flowser

Flowser — отличный инструмент с графическим интерфейсом для визуализации блокчейна эмулятора Flow. Это делает разработку более простой, потому что позволяет вам проверять, что происходит в сети, и вы можете думать об этом как о графическом интерфейсе для вашего эмулятора, но он также содержит больше функций, таких как проверка хранилища учетной записи. Вы можете запустить как эмулятор, так и кошелек разработчика от Flowser. Загрузите его и узнайте больше об этом на их веб-сайте https://flowser.dev/

‍

Расширение VSCode Cadence

Последний инструмент, который мы рассмотрим, — это расширение Visual Studio Code Cadence, которое лучше всего подходит для разработки Cadence, поскольку расширение поддерживает подсветку синтаксиса, автозаполнение, проверку кода и многое другое. Вы можете получить IDE здесь ; расширение доступно на торговой площадке .

Другие инструменты

Многие другие инструменты и библиотеки, созданные сообществом, могут помочь вам в процессе разработки и менее важны, чем рассмотренные нами. Узнайте больше о них на нашем портале для разработчиков .

Настройка проекта Cadence

Мы начнем с нуля, используя команду настройки Flow CLI.

‍

> flow setup helloWorld --scaffold

▸ Empty Cadence Project - Empty project containing only basic folder structure and flow.json configuration.
	Simple Cadence Project - Scaffold contains required folder structure as well as some example Cadence code.
  Web Dapp using FCL - Simple demo application using next.js and FCL with provided Cadence contracts.

‍

Это создаст новую пустую папку проекта с именем helloWorld и будет включать папку cadence, а также Flow.json.

Ваш проект поставляется с некоторыми стандартными папками, которые имеют особое назначение:

• /cadence внутри здесь находится ваш код смарт-контрактов Cadence.
• Файл конфигурации flow.json для вашего проекта, вы можете думать об этом как о package.json, но вам не нужно беспокоиться, команда flow dev настроит его для вас.

Внутри папки cadence вы найдете:

• /contracts расположение контрактов Cadence в этой папке
• /scripts расположение скриптов Cadence находится здесь
• /transactions место для транзакций Cadence находится в этой папке
• /tests все интеграционные тесты для вашего децентрализованного приложения и тестов Cadence помещаются в эту папку.

Вы можете прочитать больше о своем проекте в README.md , который был создан в папке проекта, но мы также расскажем обо всем здесь.

Теперь запустите среду разработки, запустив Flowser, нажав «Создать новый проект» и выбрав имя и папку, которую мы только что создали, или вручную запустив эмулятор Flow и dev-wallet Flow в каталоге проекта. Мы предлагаем использовать первый вариант, так как им проще управлять.

Вот что вы должны увидеть:

‍

Как видите, несколько учетных записей уже созданы. Первая — это служебная учетная запись, такая как учетная запись «администратора» в сети Flow, и другие учетные записи, содержащие предварительно развернутые контракты. Не нужно напрягаться по этому поводу сейчас. Мы можем пока игнорировать это.

Затем в каталоге вашего проекта запустите команду flow dev, которая будет следить за любыми изменениями в папке контрактов и следить за тем, чтобы они были развернуты для вас в сети, чтобы вы могли сосредоточить свое внимание на кодировании. Мы сделаем это, открыв проект в VSCode и запустив Flow разработки в терминале внутри VSCode. Убедитесь, что вы установили расширение Cadence.

Теперь ваша IDE должна выглядеть так:

Написание вашего первого контракта с Cadence

Мы начнем с добавления нового контракта в папку cadence/contracts с именем Person.cdc и содержимым.

‍

pub contract Person {}

‍

Нажмите «Сохранить», и все готово.

🎉 Поздравляем, вы только что развернули свой первый контракт в сети Flow.

Случилось так, что запущенная вами команда flow dev обнаружила новые контракты в папке контрактов и автоматически развернула контракт на запущенном вами эмуляторе.

Давайте сделаем контракт Person более интересным, чтобы мы могли затем написать скрипт для его запроса и транзакцию для изменения некоторых данных.

Добавьте в договор:

pub contract Person {
	pub var name: String
	
	
	init() {
	    self.name = "Alice"
	}
	
	pub fun sayHello(): String {
	    return "Hello, my name is ".concat(self.name)
	}
}

‍

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

‍

💡 Во время разработки предлагается жестко закодировать значения в конструкторе. После завершения контракта вы должны изменить конструктор, чтобы он принимал значения в качестве параметров функции.

‍

Нажмите «Сохранить» еще раз, и контракт будет автоматически обновлен.

Скрипты

Вы помните, как мы упоминали, что скрипты Flow — это программы Cadence, которые могут что-то считывать из блокчейна Flow и возвращать данные, но не могут что-то изменить? Теперь скрипты помогут нам запросить контракт и вызвать метод sayHello().

Давайте напишем скрипт с именем sayHello.cdc и поместим его в папку скриптов /cadence/scripts. Добавьте в него этот контент:

‍

import "Person"

pub fun main(): String {
    return Person.sayHello()
}

‍

Это импортирует развернутый контракт, который мы только что создали, по его имени. Затем мы можем вызвать функцию, определенную в контракте, с именем sayHello(), которая возвращает строку, поэтому мы возвращаем ее как значение, возвращаемое скриптом.

Теперь мы можем проверить это, выполнив скрипт с помощью CLI Flow:

> flow scripts execute ./cadence/scripts/sayHello.cdc

Result: "Hello, my name is Alice"

‍

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

Транзакции

Прежде всего, позвольте мне сказать, что мы могли бы вызвать ту же функцию, используя транзакцию, но это мало что дало бы, поэтому мы хотим вызвать функцию, которая что-то меняет. Давайте добавим такую ​​функцию в контракт Person. Давайте добавим ресурс дружбы и функцию, которая создает этот ресурс. Если вы хотите узнать о ресурсах, ознакомьтесь с документацией по ресурсам Cadence . Добавьте это в контракт Person:

‍

pub fun makeFriends(): @Friendship {
    return <-create Friendship()
}

pub resource Friendship {
    init() {}
    pub fun yaay() {
        log("such a nice friend") 
    }
}

‍

Таким образом мы добавляем новую функцию makeFriends(), которая возвращает ресурс Friendship. Теперь давайте вызовем эту функцию в транзакции.

Добавьте новый файл транзакции в папку cadence/transactions с именем makeFriends.cdc и поместите в него этот код:

import "Person"

transaction {
    let acc: AuthAccount

    prepare(signer: AuthAccount) {
        self.acc = signer    
    }

    pre {}

    execute {
        self.acc.save<@Person.Friendship>(<-Person.makeFriends(), to: StoragePath(identifier: "friendship")!)
    }

    post {}
}

‍

Итак, мы определили транзакцию, и если вы хотите узнать больше о транзакциях, вы можете здесь, но то, что будет делать, это сначала импортировать контракт Person, который мы определили и автоматически развернули, затем он вызовет метод Person.makeFriends(), который вернет ресурс, который будет напрямую сохранен в хранилище учетной записи. Итак, давайте подружимся и отправим транзакцию с помощью Flow CLI.

‍

> flow transactions send ./cadence/transactions/makeFriends.cdc

Transaction ID: 5d0ae2d6937913a9e5d2acb35c2daa4498791a429e4e0b78932c16ce5d133bfb

Status		✅ SEALED
ID		5d0ae2d6937913a9e5d2acb35c2daa4498791a429e4e0b78932c16ce5d133bfb
Payer		f8d6e0586b0a20c7
Authorizers	[f8d6e0586b0a20c7]

Proposal Key:	
    Address	f8d6e0586b0a20c7
    Index	0
    Sequence	10

No Payload Signatures

Envelope Signature 0: f8d6e0586b0a20c7
Signatures (minimized, use --include signatures)

Events:	 None


Code (hidden, use --include code)

Payload (hidden, use --include payload)

‍

Итак, мы видим, что транзакция была ЗАПЕЧАТЛЕНА, что означает, что она была включена в блокчейн Flow. Выполнение также прошло успешно, иначе мы бы увидели ошибку. Можем ли мы проверить, действительно ли ресурс был сохранен в аккаунте? а какой аккаунт был изначально? Таким образом, мы видим, что плательщиком является f8d6e0586b0a20c7, который является учетной записью, которая использовалась по умолчанию, если мы не определим учетную запись явно, будет использоваться эта учетная запись службы. Думайте об этом как об учетной записи администратора по умолчанию, которую мы всегда получаем в эмуляторе.

Давайте заглянем во Flowser, найдем указанную выше учетную запись и проверим хранилище. Мы видим, что в разделе хранилища действительно есть ресурс «дружбы».

‍

Поздравляем, вы изменили блокчейн Flow навсегда, пока не перезапустите эмулятор. Вы видите, что при перезапуске эмулятора данные очищаются. Если вы хотите сохранить данные блокчейна эмулятора между перезапусками, вы должны добавить флаг --persist при запуске эмулятора следующим образом: эмулятор Flow --persist

Но давайте развернем наш проект в тестовой сети, а затем в основной сети и навсегда изменим блокчейн Flow.

Переход с эмулятора на тестовую сеть

Развернуть наш только что созданный проект в тестовой сети несложно, но для этого нам нужно сначала создать учетную запись в тестовой сети, которую мы можем использовать для развертывания контрактов.

Создание учетной записи тестовой сети

Создать учетную запись testnet легко, используя Flow CLI, выполнив следующую команду в каталоге проекта:

> flow accounts create

Enter an account name: alice
✔ Testnet

🎉 New account created with address 0x4298b11728f7594a and name alice on Testnet network.

Here’s a summary of all the actions that were taken:
 - Added the new account to flow.json.
 - Saved the private key to alice.pkey.
 - Added alice.pkey to .gitignore.

‍

Введите новое имя учетной записи и выберите testnet в качестве сети. После этого вы должны увидеть приведенный выше вывод. Обратите внимание, что адрес в вашем случае будет другим.

Итак, мы видим, что учетная запись была создана и сохранена в файле flow.json, но ее ключ был добавлен в отдельный файл , которым мы никогда не должны делиться ни с кем .

Теперь нам нужно определить развертывание, которое мы хотим использовать в тестовой сети. В нашем случае это будет просто, так как у нас есть только один контракт, и нам нужно, чтобы этот контракт был развернут во вновь созданной учетной записи. Запускаем другую команду CLI:

‍

> flow config add deployment

✔ testnet
✔ alice
✔ Person
✔ No

Deployment added to the configuration.
You can deploy using 'flow project deploy' command

‍

Итак, мы выбираем testnet в качестве сети для развертывания, имя только что созданной учетной записи (alice в нашем случае), контракт «Person», который мы хотим развернуть, и все.

Как уже сказано, теперь мы можем развернуть наш проект, выполнив команду развертывания проекта, поэтому давайте сделаем это:

‍

> flow project deploy --network testnet

Deploying 1 contracts for accounts: alice

Person -> 0x4298b11728f7594a (a3789291552b550cd34aea7a7c7587d5fbb6a1754c266f029303973f1892a4f3)

🎉 All contracts deployed successfully

‍

Там написано, что мы развернули один контракт на аккаунт Алиса. Поздравляем, мы только что развернули контракт в тестовой сети 🎉

Обновление контрактов

Что, если мы хотим изменить наши развернутые контракты, скажем, мы изменим доступность имени переменной с public pub на private priv, например:

priv var name: String

Мы можем легко обновить контракты, добавив флаг --updae к приведенной выше команде следующим образом:

> flow project deploy --network testnet --update

Deploying 1 contracts for accounts: alice

Person -> 0x4298b11728f7594a (1f3dd298292898a78f1af526da2840d97b3dbd87ed159593939e786704c529e2) [updated]

🎉 All contracts deployed successfully

‍

Мы видим, что контракт «Персона» был обновлен.

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

Поскольку мы создали контракт в тестовой сети, мы можем попытаться взаимодействовать с ним, используя тот же скрипт и транзакции, что и раньше. Хорошие новости, команда остается прежней, и вам вряд ли нужно что-то менять.

Выполните скрипт, добавив флаг --network testnet следующим образом:

> flow scripts execute ./cadence/scripts/sayHello.cdc --network testnet

Result: "Hello, my name is Alice"

И транзакция путем добавления флага --network testnet, а также флага подписанта, установленного для созданной нами учетной записи --signer alice

> flow transactions send ./cadence/transactions/makeFriends.cdc --network testnet --signer alice
Transaction ID: 2921b4196d69b709ea81c047f51914636ec4d14829f36d862d71e12712c6bbeb

Status		✅ SEALED
ID		2921b4196d69b709ea81c047f51914636ec4d14829f36d862d71e12712c6bbeb
...

‍

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

🎊 Поздравляю. вы только что взаимодействовали с тестовой сетью!

Переход от Testnet к Mainnet

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

❗🚨 Прежде чем мы это сделаем, нужно отметить пару очень важных вещей:

• Создание учетной записи в основной сети — это простая процедура, не отличающаяся от той, что используется в тестовой сети, но ключи учетной записи всегда должны быть в безопасности. Любой, кто получит доступ к этим ключам, может изменить контракт и использовать ваше приложение. Мы даже предлагаем защитить вашу учетную запись с помощью Amazon или Google KMS для подписи .
• Развертывание в основной сети должно быть самым последним действием в процессе разработки, то есть вы должны убедиться, что ваше приложение работает хорошо, тщательно протестировано и не содержит ошибок.

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

После всех заявлений давайте создадим учетную запись основной сети с помощью CLI:

> flow accounts create

Enter an account name: bob
✔ Mainnet

🎉 New account created with address 0xbd9b4d46cb027518 and name bob on Mainnet network.

Here’s a summary of all the actions that were taken:
 - Added the new account to flow.json.
 - Saved the private key to bob.pkey.
 - Added bob.pkey to .gitignore.

Добавьте развертывание:

> flow config add deployment
✔ mainnet
✔ bob
✔ Person
✔ No

Deployment added to the configuration.
You can deploy using 'flow project deploy' command

И разверните в основной сети с помощью команды CLI:

> flow project deploy --network mainnet --update

Deploying 1 contracts for accounts: bob

Person -> 0xbd9b4d46cb027518 (e3d6086934f634173cd0a0216d6b787b70b714f9258348406714b084cc38d061) [updated]

🎉 All contracts deployed successfully

Вы сделали. Вы успешно развернули свое приложение в основной сети.

Поздравляю 🎊 🎉

Как мы можем проверить развертывание? мы можем использовать flowcan и ввести адрес учетной записи, используемой в развертывании (той, которую мы только что создали ранее), например так:

https://flowscan.org/account/0xbd9b4d46cb027518

И мы видим, что он включает наш контракт https://flowscan.org/contract/A.bd9b4d46cb027518.Person .