Привет! Меня зовут Даниил, я разработчик в 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 — инструменте для обработки смайненных транзакций. А еще о постквантовой криптографии… но это уже совсем другая история :