Шлюз Fabric

Шлюз Fabric (Fabric Gateway) - это служба, представленная в одноранговых узлах Hyperledger Fabric версии 2.4, которая предоставляет упрощенный, минимальный API для отправки транзакций в сеть Fabric. Требования, ранее предъявлявшиеся клиентским SDK, такие как сбор одобрений транзакций с одноранговых узлов разных организаций, в версии 2.4 переданы шлюзу Fabric, работающему внутри одноранговых узлов, для упрощения разработки приложений и отправки транзакций.

Написание клиентских приложений

Начиная с версии Fabric 2.4, клиентские приложения должны использовать один из API шлюза Fabric (для Go, Node или Java), которые оптимизированы для взаимодействия со шлюзом Fabric. Эти API представляют ту же высокоуровневую модель программирования, которая была введена в Fabric версии 1.4.

Служба Fabric Gateway (она же шлюз) управляет следующими действиями с транзакциями:

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

Клиентские API шлюза Fabric объединяют действия Endorse/Submit/CommitStatus в одну функцию SubmitTransaction для реализации отправки транзакции одной строчкой кода. В качестве альтернативы можно выполнять отдельные действия для поддержки гибких моделей приложений.

Клиентские API приложений

Шлюз и его клиентский API разработаны таким образом, чтобы позволить вам как разработчику клиентского приложения сосредоточиться на бизнес-логике вашего приложения, не заботясь о логике инфраструктуры, связанной с сетью Fabric. То есть API предоставляют логические абстракции, такие как организация и контракт, а не операционные, как узел или чейнкод. [Примечание: очевидно, что API администратора должно раскрыть эти операционные абстракции, но мы говорим не об API администратора].

Hyperledger Fabric в настоящий момент поддерживает разработку приложений на трех языках программирования:

Как шлюз одобряет предложение транзакции

Для того чтобы транзакция была успешно записана в реестр, нужно получить необходимое число одобрений, удовлетворяющее политике одобрения. Получить одобрение от организации можно, подключившись к одному из ее одноранговых узлов и попросив его симулировать (выполнить) предложение транзакции на своей копии реестра. Узел симулирует транзакцию, вызывая функцию чейнкода с указанными в предложении транзакции именем и аргументами, и формирует и подписывает набор чтения-записи. Результаты исполнения инструкций получения и установки состояния, которые вызываются внутри функции, формируют набор чтения-записи, содержащий текущее состояния реестра и его предлагаемые изменения.

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

  • Политики одобрения чейнкодов. Это политики, с которыми соглашаются члены канала, когда они утверждают определение чейнкода для своих организаций. Если функция чейнкода вызывает функцию в другом чейнкода, то политики обоих чейнкодов должны быть удовлетворены.
  • Политики одобрения коллекций приватных данных. Если функция чейнкода осуществляет запись состояния в коллекции приватных данных, тогда политика одобрения для этой коллекции переопределит политику чейнкода для этого состояния. Если функция чейнкода читает данные из коллекции приватных данных, то она будет ограничена организациями, входящими в эту коллекцию.
  • Политики одобрения на уровне состояния (SBE - state-based endorsement). Также известные как политики подписания на уровне ключа, они могут применяться к отдельным состояниям и отменяют политику одобрения чейнкода и политику одобрения коллекций приватных данных.

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

Шлюз Fabric управляет сложностью одобрения транзакций от имени клиента, следуя следующему процессу:

  • Шлюз Fabric выбирает одобряющий одноранговый узел из организации узла шлюза (MSP ID), определяя (доступный) узел с наибольшей длиной цепочки блоков. Предполагается, что все одноранговые узлы организации узла шлюза являются доверенными для клиентского приложения, которое подключается к шлюзу.
  • Предложение транзакции симулируется на выбранном одобряющем узле. Это симуляция собирает информацию о доступных состояниях и, следовательно, о политиках одобрения, которые будут объединены (включая любые политики на уровне состояния, хранящиеся в реестре одобряющего узла).
  • Полученная информация о политиках собирается в сообщение ChaincodeInterest и передается в службу обнаружения для получения плана одобрения для конкретной предлагаемой транзакции.
  • Шлюз применяет план одобрения, запрашивая одобрение у организаций, необходимых для удовлетворения всех политик в плане. При этом в каждой организации одобрение запрашивается у (доступного) однорангового узла с наибольшей длиной цепочки блоков.

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

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

Указание конкретных одобряющих узлов

В некоторых случаях клиентское приложение должно явно выбрать организации для оценки или одобрения предложения транзакции. Например, транзитные данные часто содержат персональную или конфиденциальную информацию, которая должна быть записана только внутри коллекции приватных данных, тем самым ограничивая круг одобряющих организаций. В таких ситуациях клиентское приложение может явно указать одобряющие организации, чтобы удовлетворить требованиям одобрения и конфиденциальности; после этого шлюз выберет (доступный) одобряющий узел с наибольшим количеством блоков в цепочке из каждой из указанных организаций. Если клиент указывает набор организаций, не удовлетворяющий политике одобрения, транзакция все равно может быть одобрена указанными узлами и передана для упорядочивания, но впоследствии, на этапе валидации и записи, она будет признана недействительной всеми узлами в канале. Такая недействительная транзакция записывается в реестр, но ее обновления не применяются к состоянию ни на одном одноранговом узле в канале.

Повтор действий и обработка ошибок

Шлюз Fabric выполняет повторные попытки соединения с узлом, обрабатывает ошибки и истечение времени ожидания, как описано ниже.

Повторные попытки

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

Обработка ошибок

Шлюз Fabric управляет соединениями gRPC с одноранговыми и упорядочивающими узлами в сети. Если ошибка, полученная на запрос к шлюзу, исходит от однорангового или упорядочивающего узла (внешнего по отношению к шлюзу), шлюз возвращает клиенту информацию об этой ошибке, конечной точке и организации (MSP ID) в поле Details сообщения. Если поле Details пустое, то ошибка исходит от узла, на котором работает шлюз.

Истечение времени ожидания

Методы шлюза Fabric Evaluate и Endorse выполняют запросы gRPC к внешним по отношению к шлюзу одноранговым узлам. Чтобы ограничить время ожидания коллективных ответов клиентом, значение параметра peer.gateway.endorsementTimeout может быть переопределено в секции gateway конфигурационного файла core.yaml на одноранговом узле.

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

Прослушивание событий

Шлюз предоставляет упрощенный API для получения событий чейнкода в клиентских приложениях. Клиентский API предоставляет механизм для обработки этих событий, используя особенности языка, на котором он реализован.