Привет! Меня зовут Даниил, я разработчик в Web3 Tech. Недавно в JVM-инструментарии для нашей основной платформы «Конфидент» состоялся новый релиз, в который вошли библиотеки клиента для взаимодействия с нодой и Spring Boot стартеры. Далее в посте я расскажу об этих библиотеках, которые помогут вам комфортно и эффективно создавать на JVM-языках программирования полноценные приложения, взаимодействующие со смарт-контрактами нашей платформы.

Какие JVM-библиотеки у нас вообще есть

Прежде чем рассказывать о конкретных решениях, перечислю, что входит в инструментарий для разработки на JVM-языках, который мы недавно обновили:

we-node-client — библиотека, предоставляющая клиент для взаимодействия с нодами;
we-sdk-contract — библиотека для создания смарт-контрактов; подробней о ней можно узнать в посте моего коллеги Степана;
we-sdk-spring — библиотека, содержащая стартеры с автоконфигурациями для клиентов ноды и контракта;
we-tx-observer — инструмент для обработки смайненных транзакций в блокчейне.

Далее я подробней расскажу о we-node-client и we-sdk-spring, а также немного о we-tx-observer.

Библиотека клиента ноды (we-node-client)

Основная задача we-node-client — взаимодействие с нодой через предоставление абстрактных сервисов конечному пользователю. Все наши библиотеки используют в своих реализациях we-node-client — через него организовано взаимодействие с нодами блокчейн-сети.

We-sdk-contract использует we-node-client для получения транзакций 103 и 104 (создание и вызов смарт-контракта соответственно) из UTX (пула неподтвержденных транзакций) — с целью их майнинга через исполнение смарт-контракта. Для отправки транзакций используется клиент для работы с контрактом (проводник для отправки транзакций контракта), который, в свою очередь, использует we-node-client.
We-tx-observer использует we-node-client для периодического опроса ноды (или подписки на события новых блоков, при использовании gRPC) с целью прослушивания актуальных транзакций и высоты смайненных блоков.
We-sdk-spring предоставляет Spring Boot автоконфигурации для удобного создания и конфигурирования клиентов, работающих с нодами и контрактами.

У we-node-client есть два типа подключения — через http и gRPC. Первый пока реализован через Feign (FeignNodeServiceFactory). Для gRPC-клиента используется GrpcNodeServiceFactory. Обе реализализации являются наследниками общего интерфейса NodeBlockingServiceFactory. Он предоставляет сервисы для взаимодействия с нодой, которые соответствуют эндпоинтам REST API со стороны ноды.

Список сервисов и их соответствие эндпоинтам в Swagger’е ноды:

TxService - /transactions
ContractService - /contracts
AddressService - /addresses
NodeInfoService - /node
PrivacyService - /privacy
BlocksService - /blocks
NodeUtilsService - /utils
PkiService - /pki

Список методов и их описание есть у нас в документации.

Обертки с дополнительной логикой

Библиотека клиента ноды включает обертки с дополнительной логикой для оптимизации работы с нодой (нодами).

RateLimitingServiceFactory ограничивает число запросов к нодам для предотвращения перегрузки.

Логика работы этой обертки опирается на количество транзакций в UTX-пуле ноды. Если достигнут некий установленный лимит, то запросы к этой ноде перестают поступать до уменьшения числа транзакций в пуле.

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

CachingNodeBlockingServiceFactory предназначена для снижения нагрузки на сеть при взаимодействии с нодой. Она кеширует необходимую информацию по транзакциям сети:

BlocksService — при получении блока транзакций на определенной высоте blockAtHeight(height: Long) или последовательности блоков blockSequence(fromHeight: Long, toHeight: Long) транзакции из них кешируются.
PrivacyService — при получении метаданных для пакета конфиденциальных данных группы info(request: PolicyItemRequest) полученная информация кешируется; либо берется из кеша, если была ранее сохранена в нем.
TxService — при запросах информации по транзакциям txInfo(txId: TxId) транзакция кешируется; либо берется из кеша, если уже присутствует в нем.

AtomicAwareNodeBlockingServiceFactory используется при выполнении атомарных транзакций. С ее помощью в рамках одного метода можно собрать все транзакции, подписать их одновременно и отправить в виде атомарной транзакции. Обертка не имеет отдельных настроек: она просто оборачивает существующего клиента к ноде при добавлении зависимости we-starter-atomic из проекта we-sdk-spring. И переопределяет методы сервисов, которые отправляют транзакции:

TxService — отправка broadcast(tx: Tx) и подписание + отправка signAndBroadcast(request:SignRequest<T>) транзакций;
PrivacyService — отправка 114 транзакции методом sendData(request: SendDataRequest) с параметром broadcast = false.

Далее у нас есть два способа объединения транзакций в одну атомарную. Можно либо пометить метод с кодом отправки транзакций аннотацией @Atomic, либо использовать метод atomicManager.doInAtomic.

Подробнее про настройку и использование оберток можно узнать в документации we-node-client и we-sdk-spring.

Библиотека для обработки и отслеживания транзакций (we-tx-observer)

We-tx-observer предоставляет удобный способ обработки и отслеживания транзакций в блокчейн-сети. Библиотека использует постоянную очередь для хранения транзакций, которые далее передаются обработчикам, настроенным в пользовательском приложении. Есть возможность отбора и обработки транзакций по заданным фильтрам.

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

сервис, который наследует TxEnqueuePredicate;
метод приложения, помеченный аннотацией @TxListener.

Я проиллюстрирую работу библиотеки в примере далее; более подробная информация есть в документации we-tx-observer.

Библиотека стартеров с автоконфигурациями (we-sdk-spring)

We-sdk-spring — это набор Spring Boot стартеров, позволяющий с минимальными дополнительными настройками сконфигурировать контекст приложения для работы с клиентами ноды (включая необходимые обертки) и с клиентами контракта.

В сообществе Hyperledger Fabric есть известный пример разработки — приложение rent-car-app. По сути, это простая ролевая модель, где любой желающий может заказать уже существующее свободное авто, но только создатель контракта может принудительно изменять владельца и создавать новые авто. Вот как будет выглядеть схема взаимодействия с нодой (нодами), если мы сделаем это приложение на нашей платформе:

Теперь воспроизведем нужную логику на Java 17. Вот интерфейс контракта:

public interface RentCarContract {

    @ContractInit
    void initRent();

    @ContractAction
    void rentCar(@InvokeParam(name = "carNumber") String carNumber);

    @ContractAction
    void createCar(@InvokeParam(name = "car") Car car);

    @ContractAction
    void changeCarRenter(
            @InvokeParam(name = "carNumber") String carNumber,
            @InvokeParam(name = "carRenter") String carRenter
    );

    class Keys {
        public static final String CONTRACT_CREATOR = "CONTRACT_CREATOR";
        public static final String CARS_MAPPING_PREFIX = "CARS";
    }
}

Вот реализация:

@ContractHandler
public class RentCarContractImpl implements RentCarContract {

    private final ContractState contractState;
    private final ContractCall call;
    private final Mapping<Car> cars;

    public RentCarContractImpl(ContractState contractState, ContractCall call) {
        this.contractState = contractState;
        this.call = call;
        this.cars = contractState.getMapping(Car.class, CARS_MAPPING_PREFIX);
    }

    @Override
    public void initRent() {
        contractState.put(CONTRACT_CREATOR, call.getCaller());
        cars.put("1", new Car("beatle", null, "1"));
        cars.put("2", new Car("banana", null, "2"));
        cars.put("3", new Car("cat", null, "3"));
    }

    @Override
    public void rentCar(String carNumber) {
        Car car = getCarIfExist(carNumber);
        checkPossibilityRentCar(car);
        car.setRenter(call.getCaller());
        cars.put(carNumber, car);
    }

    @Override
    public void createCar(Car car) {
        checkContractCreator();
        cars.put(car.getNumber(), car);
    }

    @Override
    public void changeCarRenter(String carNumber, String carRenter) {
        checkContractCreator();
        Car car = getCarIfExist(carNumber);
        car.setRenter(carRenter);
        cars.put(carNumber, car);
    }

    private void checkPossibilityRentCar(Car car) {
        if (car.getRenter() != null) {
            throw new IllegalStateException("Car with number " + car.getNumber() + " has owner.");
        }
     }

     private void checkContractCreator() {
         String contractCreator = contractState.get(CONTRACT_CREATOR, String.class);
         if (!contractCreator.equals(call.getCaller())) {
             throw new IllegalStateException("Only contract creator can create cars or change car owner.");
         }
     }

     private Car getCarIfExist(String carNumber) {
         Optional<Car> optionalCar = cars.tryGet(carNumber);
         return optionalCar.orElseThrow(() -> new IllegalStateException(
                 "Car with number " + carNumber + " not exist."
         ));
     }
}

Далее необходимо добавить образ контракта в репозиторий — подробней об это можно почитать в посте «Как войти в блокчейн-разработку через Java и Kotlin: представляем JVM SDK смарт-контрактов» и в документации к we-contract-sdk.

После добавления образа контракта в репозиторий, на который смотрит нода, необходимо реализовать бэкенд для взаимодействия с контрактом через клиента. Основные компоненты бэкенда:

Spring-конфигурация;
сервис работы с клиентом контракта;
предикат и листенер для фильтрации и обработки смайненных транзакций;

Вот Spring-конфигурация контракта RentCarContract и компонента клиента к ноде SenderAddressProvider:

@Configuration
@EnableContracts(
        contracts = {
                @Contract(
                        api = RentCarContract.class,
                        impl = RentCarContractImpl.class,
                        name = "rentCarContract"
                )
        }
)
public class RentCarAppConfiguration {
  
    @Bean
    SenderAddressProvider senderAddressProvider() {
        return new HttpSenderAddressProvider();
    }
  
}

С помощью аннотации @EnableContracts конфигурация определяет контракты, для которых необходимо создать клиентов. Аннотация @Contract определяет интерфейс, реализацию и названия контракта для связывания через настройки контракта в yml-файле. Также здесь присутствует бин пользовательской реализации SenderAddressProvider’а — он необходим для определения отправителя при отправке транзакций контракт-клиентом. Реализация использует переданный в хедер X-Tx-Sender адрес для реализации ролевой модели контракта.

Вот как выглядит конфигурация контракт-клиента в application.yml. По имени контракта определяются образ, хеш образа, версия транзакции, комиссия за вызовы контракта:

contracts:
  config:
    rentCarContract:
      image: registry.hub.docker.com/donyfutura/contract:0.0.1
      imageHash: e95dfce7fb4ca9ef7f5e6a829467a4c65284689d9dcfe00daed1f96d3a2999e4
      version: 3
      fee: 0
      auto-update:
        enabled: false
        contractCreatorAddress: null

Вот конфигурация для клиента ноды:

node:
  config:
    node-0:
      http:
        url: http://158.160.97.253:6862
        loggerLevel: FULL
        read-timeout: 30000
      grpc:
        address: node-0
        port: 6865

В ней настроен клиент к ноде без оберток для http и gRPC; gRPC используется для прослушивания транзакций из блокчейна через we-tx-observer. Также настройки включают в себя значения credentials-provider — они нужны для определения пароля отправителя по адресу для подписания транзакций (если нода настроена на работу с транзакциями с паролем).

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

Для взаимодействия с контрактом мы реализуем сервис RentCarService, который инжектит в себя бин необходимого контракт-клиента (ContractBlockingClientFactory<RentCarContract>). Согласно коду, возможен вызов двух типов транзакций — 103 (создание контракта на ноде) и 104 (вызов контракта):

@Service
public class RentCarService {
    private ContractBlockingClientFactory<RentCarContract> contractClient;
    private CarRepository carRepository;

    @Autowired
    public void setContractClient(
            ContractBlockingClientFactory<RentCarContract> contractClient,
            CarRepository carRepository
    ) {
        this.contractClient = contractClient;
        this.carRepository = carRepository;
    }

    public String initRent() {
        ExecutionContext executionContext = contractClient.executeContract(
                null, (RentCarContract rentCarContract) -> {
                    rentCarContract.initRent();
                    return null;
                });
        return executionContext.getTx().getId().asBase58String();
    }

    public String rentCar(String carNumber, String contractId) {
        ExecutionContext executionContext = contractClient.executeContract(
                ContractId.fromBase58(contractId), (RentCarContract rentCarContract) -> {
                    rentCarContract.rentCar(carNumber);
                    return null;
                });
        return executionContext.getTx().getId().asBase58String();
    }
    ...
}

После всех настроек и реализации взаимодействия с контрактом нужно написать предикат и листенер транзакций для получения актуальной информации на стейте контракта. Код предиката:

@Service
public class RentCarPredicate implements TxEnqueuePredicate {

    private ContractService contractService;

    @Value("${contracts.config.rentCarContract.image}")
    private String rentCarContractImage;

    @Autowired
    public RentCarPredicate(ContractService contractService) {
        this.contractService = contractService;
    }


    @Override
    public boolean isEnqueued(Tx tx) {
        return switch (tx) {
            case ExecutedContractTx executedContractTx -> rentCarContractImage.equals(getImage(executedContractTx));
            default -> false;
        };
    }

    private String getImage(ExecutedContractTx executedContractTx) {
        return switch (executedContractTx.getTx()) {
            case CallContractTx callContractTx ->
                    contractService.getContractInfo(callContractTx.getContractId()).get().getImage().getValue();
            case CreateContractTx createContractTx -> createContractTx.getImage().getValue();
            case UpdateContractTx updateContractTx -> updateContractTx.getImage().getValue();
            default -> null;
        };
    }
}

Что здесь происходит? Простыми словами, каждая полученная транзакция, связанная с вызовом контракта, проверяется на соответствие «нужно ли нам, чтобы она попала в слушатель, или нет?». В этом примере идет проверка по названию образа из полученной транзакции: если образ совпадает с ожидаемым, то транзакция попадет в слушатель. Реализация определяет Spring-бин наследника TxEnqueuePredicate (базовый интерфейс предикатов), который используется для фильтрации библиотекой we-tx-observer при получении новых транзакций из сети блокчейн.

Перейдем к листенеру (слушателю) — это обычный Spring-сервис, который определяет методы, аннотированные @TxListener:

@Service
public class RentCarListener {

    private CarRepository carRepository;

    @Autowired
    public RentCarListener(CarRepository carRepository) {
        this.carRepository = carRepository;
    }

    Logger log = LoggerFactory.getLogger(RentCarListener.class);

    @TxListener
    public void onCallRentCar(
            @KeyFilter(keyPrefix = "CARS_") KeyEvent<Car> keyEvent
    ) {
        Car car = keyEvent.getPayload();
        log.info("Received 104 tx [ id = {} ]", keyEvent.getTx().getId().asBase58String());
        carRepository.save(mapToEntity(car));
    }

    private CarEntity mapToEntity(Car car) {
        return new CarEntity(car.getNumber(), car.getName(), car.getRenter());
    }
}

В примере мы определяем метод onCallRentCar(KeyEvent<Car> keyEvent), куда попадают ивенты по префиксу ключа, измененного на стейте.

Транзакция, которую получит на обработку слушатель в объекте KeyEvent<Car>, будет соответствовать названию образа, а также содержать в параметрах ключ с префиксом CARS_ и объект Car в значении. Например, если будет вызван метод контракта rentCar(String carNumber), то после майнинга 105-й транзакции, содержащей в себе results нашего вызова, метод, аннотированный @TxListener, получит в обработку ожидаемый KeyEvent<Car> и сохранит в БД новую информацию.

Пример транзакции, которая будет прослушана реализованным нами слушателем:

{
  "senderPublicKey": "3BDjUQy6umvupLY2YR13VXnrjb5QAzMbRsFCFEQEXKVcQ8AHMGXiBC2YUJBXRUDimqnpuUFYA7QEMTi9c6cebipa",
  "tx": {
    "senderPublicKey": "4L4XEpNpesX9r6rVJ8hW1TrMiNCZ6SMvRuWPKB7T47wKfnp4D84XBUv7xsa36CGwoyK3fzfojivwonHNrsX2fLBL",
    "fee": 0,
    "type": 104,
    "params": [
      {
        "type": "string",
        "value": "rentCar",
        "key": "action"
      },
      {
        "type": "string",
        "value": "2",
        "key": "carNumber"
      }
    ],
    "version": 4,
    "contractVersion": 1,
    "atomicBadge": null,
    "sender": "3M3ybNZvLG7o7rnM4F7ViRPnDTfVggdfmRX",
    "feeAssetId": null,
    "proofs": [
      "DqtSCN72ZgW6RLG2AfRYsSy4jbnsthFMkyVTHCnwRD6ichxTUSuC6emVHETjCFnEvvgsb7GojLnNa4arcRi4wCn"
    ],
    "contractId": "6Qmz51WdR1iaDvjbvuMrduLE6xbnBpd21Yw3F7gVfLjG",
    "id": "Ge1bYCWNQtyfzdW8b2QYrznmzcMFkYUQuZC8z1AWV7v7",
    "timestamp": 1695740795467
  },
  "resultsHash": "HDRCWodoLvr6q3vmkPejPiwqVxhpf1NyQQvcvcLiXoGV",
  "fee": 0,
  "validationProofs": [],
  "type": 105,
  "version": 3,
  "sender": "3M7EEnszPAT2yr72SgWVDLxfYCa4AYvVRwv",
  "assetOperations": [],
  "proofs": [
    "aLNwwsbi4jx9AtCeQmWwD3Gf4pje4rVzb4KadvNE6LzmUDxCSd3bxihpx74hSvdxNE9ooeRGBxS1gESFvnvnfqE"
  ],
  "id": "Ekfec5VEGgdnfjfVDadBvWuBqU1hWit9BEodN3tv2M8U",
  "results": [
    {
      "type": "string",
      "value": "{\"lang\":\"java\",\"interfaces\":[\"com.wavesenterprise.contract.api.RentCarContract\"],\"impls\":[\"com.wavesenterprise.contract.app.RentCarContractImpl\"]}",
      "key": "__WRC12_CONTRACT_META"
    },
    {
      "type": "string",
      "value": "{\"name\":\"banana\",\"owner\":\"3M3ybNZvLG7o7rnM4F7ViRPnDTfVggdfmRX\",\"number\":\"2\"}",
      "key": "CARS_2"
    }
  ],
  "timestamp": 1695740799662,
  "height": 11924439
}

Полный код примера можно найти у нас гитхабе. В ближайших постах в блоге Web3 Tech мы подробней расскажем о we-tx-observer — инструменте для обработки смайненных транзакций. А еще о постквантовой криптографии… но это уже совсем другая история.

Разработка децентрализованных приложений на Spring Boot: инструменты Web3 Tech