Установка и использование платформы

Создание смарт-контрактов с помощью JS Contract SDK

В этом разделе описан JS Сontract SDK Toolkit – инструментарий для разработки, тестирования и развертывания смарт-контрактов в публичных блокчейн сетях Waves Enterprise. Этот инструментарий позволяет быстро освоить экосистему Waves Enterprise без использования какого-либо конкретного языка программирования, поскольку смарт-контракт разворачивается в Docker-контейнере. Вы можете создать смарт-контракт с помощью любого из наиболее часто используемых языков, например Typescript.

Контракт можно развернуть в различных средах и сетях. Например, для локальной разработки смарт-контрактов и их тестирования вы можете локально развернуть свою сеть (создать локальную среду) на основе ноды в ознакомительном режиме (Sandbox) и развернуть контракты в этой сети.

Для развёртывания контракта в различных средах используйте инструмент WE Contract Command line interface (CLI).

Системные требования

Перед началом работы убедитесь, что на вашей машине установлено следующее ПО:

  • Docker

  • Node.js (LTS)

Быстрый старт

Для создания вашего нового проекта выполните в командной строке следующую команду: С помощью npm npx

npx create-we-contract YourContractName -t path-to-contract -n package-name

или

npm create we-contract YourContractName -t path-to-contract -n package-name

или с помощью yarn

yarn create we-contract YourContractName -t path-to-contract -n package-name

Таким образом будет создан ваш первый смарт-контракт, готовый к разработке и внедрению в блокчейн Waves Enterprise. Затем выполните следующую команду для инициализации зависимостей и начала разработки проекта:

npm i // or yarn

Конфигурация

Файл конфигурации используется для того, чтобы задать имя образа и имя контракта, которые будут отображаться в проводнике. Также в файле конфигурации можно задать тег образа (свойство name), который будет использоваться для отправки контракта в реестр.

Добавьте конфигурационный файл contract.config.js в корневую директорию вашего проекта для инициализации конфигурации контракта.

Если вы создали проект с помощью команды create-we-contract (как описано выше в разделе Быстрый старт), то конфигурация настраивается по умолчанию.

Конфигурация по умолчанию

Ниже приведён пример конфигурации по умолчанию:

module.exports = {
  image: "my-contract",
  name: 'My Contract Name',
  version: '1.0.1',
  networks: {
  /// ...
  }
}

Конфигурация сети

В разделе networks задайте конфигурацию для вашей сети:

module.exports = {
  networks: {
    "sandbox": {
        seed: "#your secret seed phrase" // or get it from env process.env.MY_SECRET_SEED

        // also you can provide
        registry: 'localhost:5000',
        nodeAddress: 'http://localhost:6862',
        params: {
          init: () => ({
            paramName: 'paramValue'
          })
        }
    }
  }
}
  • seed – если вы хотите развернуть контракт в сети в ознакомительном режиме (Sandbox), укажите seed-фразу инициатора контракта;

  • registry – если вы использовали определенный реестр Docker, укажите имя этого реестра;

  • nodeAddress – укажите конкретный адрес ноды для развертывания.

  • params.init – чтобы задать параметры инициализации, задайте функцию.

Осторожно

Не публикуйте свои секретные фразы в открытых хранилищах.

Развертывание контракта

Смарт-контракты выполняются, как только они развёрнуты в блокчейне. Для развертывания контракта используйте команду deploy в WE Contract CLI:

we-toolkit deploy -n testnet

где testnet – название сети, указанное в конфигурационном файле. Например, для развертывания контракта в сети в ознакомительном режиме (Sandbox), выполните следующую команду:

we-toolkit deploy -n sandbox

Набор инструментов для разработки смарт контрактов Contract SDK Toolkit

Основные понятия

Для создания класса контракта в Contract SDK Toolkit необходимо указать аннотации к методам. Следующие аннотации являются наиболее важными:

  • Contract – регистрация класса как контракта;

  • Action – регистрация обработчика действия контракта;

  • State – декоратор свойства класса для доступа к состоянию контракта;

  • Param – декоратор, который отображает параметры транзакции на параметры действия класса контракта.

SDK предоставляет шаблоны контрактов, в которые вы можете добавить свою бизнес-логику:

@Contract
export class ExampleContract {
    @State state: ContractState;

    @Action
    greeting(@Param('name') name: string) {
        this.state.set('Greeting', `Hello, ${name}`);
    }
}

Методы

Методы управления состоянием смарт контракта

Класс ContractState предоставляет методы для записи в состояние контракта. В документации ноды описаны доступные на данный момент типы данных в состоянии контракта. Contract SDK поддерживает все доступные на данный момент типы данных в состоянии контракта.

Запись

Самый простой способ записать состояние – использовать метод set. Этот метод автоматически приводит тип данных.

this.state.set('key', 'value')

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

// for binary
this.state.setBinary('binary', Buffer.from('example', 'base64'));

// for boolean
this.state.setBool('boolean', true);

// for integer
this.state.setInt('integer', 102);

// for string
this.state.setString('string', 'example');
Считывание

Чтение состояния в настоящее время является асинхронным и зависит от конфигурации контракта.

@Contract
export class ExampleContract {
    @State state: ContractState;

    @Action
    async exampleAction(@Param('name') name: string) {
        const stateValue: string = await this.state.get('value', 'default-value');
    }
}

Осторожно

У метода state.get нет информации о типе внутреннего состояния во время выполнения. Для явного приведения типов используйте методы getBinary, getString, getBool, getNum.

Write Actions

Ключевыми декораторами являются Action и Param.

Init Actions

Для описания действия создания контракта задайте параметру onInit декоратора действия значение true.

@Contract
export class ExampleContract {
    @State state: ContractState;

    @Action({onInit: true})
    exampleAction(@Param('name') name: string) {

        this.state.set('state-initial-value', 'initialized')
    }
}

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

@Contract
export class ExampleContract {
    @State state: ContractState;

    @Action({name: 'specificActionName'})
    exampleAction() {
        // Your code
    }
}

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

Для обновления версии контракта используйте метод update. Метод обновляет последний развернутый контракт. Если ни один контракт не был развёрнут, метод ничего не обновляет.

we-cli update -n, --network <char>