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

REST API: работа с конфиденциальными смарт-контрактами

https://img.shields.io/badge/auth-required-orange.svg

Для работы с конфиденциальными смарт-контрактами предусмотрены методы группы confidential-contracts.

POST /confidential-contracts/call

Для передачи данных конфиденциальных смарт-контрактов вне блокчейна служит REST метод POST /confidential-contracts/call.

Важно

Вызов метода POST /confidential-contracts/call доступен только при использовании oAuth токена с ролью ConfidentialContractUser или специального api-key.

Метод POST /confidential-contracts/call недоступен для контрактов без поддержки конфиденциальности (isConfidential = false).

Метод POST /confidential-contracts/call возвращает ошибку, если среди участников группы авторизации (политики) менее трёх нод с ролью contract-validator.

В запросе метода указываются следующие данные:

  • broadcast – флаг, который отражает необходимость бродкаста сформированной транзакции CallContract; по умолчанию имеет значение true; значение false используется для формирования атомарного контейнера;

  • commitmentVerification – флаг, который отражает необходимость сверки коммитмента входных данных и предоставления со стороны пользователя ключа для формирования коммитмента; по умолчанию имеет значение false; при значении false нода сама формирует ключ случайным образом и рассчитывает коммитмент; если commitmentVerification имеет значение true, и пользователь не передал commitment или commitmentKey, либо передал неверно сформированное значение commitment или неверный commitmentKey, метод возвращает ошибку;

  • sender – адрес отправителя данных конфиденциального смарт-контракта;

  • contractId – идентификатор конфиденциального смарт-контракта;

  • contractVersion – версия конфиденциального смарт-контракта;

  • params – при работе с транзакцией CallContract – входные данные конфиденциального смарт-контракта, представленные как массив объектов; вносятся при помощи следующих полей:

    • key – ключ параметра;

    • type – тип данных параметра;

    • value – значение параметра.

  • timestamp – временная метка в формате Unix Timestamp (в миллисекундах), отмечающая время вызова смарт-контракта;

  • atomicBadge – флаг, который отражает возможность включать транзакцию в атомарную транзакцию;

  • fee – комиссия за транзакцию;

  • feeAssetId – идентификатор токена комиссии;

  • commitment – коммитмент;

  • commitmentKey – ключ коммитмента.

Метод POST /confidential-contracts/call принимает все данные, необходимые, чтобы отправить транзакцию CallContract версии 6, отправляет её, и в ответе возвращает protobuf, в который входит транзакция CallContract версии 6 и конфиденциальные входные данные для запуска конфиденциального смарт-контракта (ConfidentialInput).

Пример ответа:

POST /confidential-contracts/call:
{
    "callContractTransactionV6":{
       "senderPublicKey":"5oKuxwiRmqHnr7vCAHK3VRJBhg9andjskfX11HpmJcYp8JifBXisz4KEKFD3pbRum3PWHDf4ZKkoCAgrrsLbp8HH",
       "inputCommitment":"GRWajEXricyL5idiJVcCtNaedDGvBow8dZu1w8L3bRh9",
       "fee":10000000,
       "payments":[

       ],
       "type":104,
       "params":[

       ],
       "version":6,
       "contractVersion":1,
       "atomicBadge":null,
       "sender":"3Hakpx6EE4fDb7Vd7EaWMG1HT9UJezLeVcG",
       "feeAssetId":null,
       "proofs":[
           "2JExxgAjQUmr5YNpkJpo3gRYtteDbhx4ZyQtt8CB978BjKBgy8N9yfu7ikh13muRcqWaT1XwYu78xJJttEtAjc2E"
       ],
       "contractId":"BbkPS3BKzs5JFR1wLiHqvRgF8DkuajKiQkKQdKZ5Ydru",
       "id":"2kH8Y4798dqrczZgaPo7LSkmwSWq4CmN6vbr3zhNBrN4",
       "timestamp":1697788418311
    },
    "confidentialInput":{
       "commitment":"GRWajEXricyL5idiJVcCtNaedDGvBow8dZu1w8L3bRh9",
       "txId":"2kH8Y4798dqrczZgaPo7LSkmwSWq4CmN6vbr3zhNBrN4",
       "contractId":{
          "byteStr":"BbkPS3BKzs5JFR1wLiHqvRgF8DkuajKiQkKQdKZ5Ydru"
    },
    "commitmentKey":{
       "bytes":"CMtEfgK628ZT9Bc376caLwhacgozBucfXjxrmyLcrLMg"
    },
    "entries":[
       {
        "type":"integer",
        "value":1,
        "key":"test"
       }
    ]
 }

Примечание

REST методу POST /confidential-contracts/call аналогичен gRPC метод ConfidentialCall.

GET ​/confidential-contracts/{contractId}

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

Важно

Вызов метода GET ​/confidential-contracts/{contractId} доступен только участникам соответствующей политики и только при использовании oAuth токена с ролью ConfidentialContractUser или специального api-key.

В запросе метода GET ​/confidential-contracts/{contractId} указываются следующие данные:

  • contractId – идентификатор смарт-контракта;

  • limit – ограничение количества выводимых блоков данных;

  • offset – количество блоков данных для пропуска в выводе;

  • matches – опциональный параметр для составления регулярного выражения, по которому фильтруются ключи.

Пример ответа для участников политики:

GET ​/confidential-contracts/{contractId}:
[
  {
   "type": "integer",
   "value": 1,
   "key": "sum"
  }
]

Пример ответа для адреса, который не является участником политики:

GET ​/confidential-contracts/{contractId}:
{
  "error": 651,
  "message": "Confidential groups from contract '9KkLSJA8zXKtnCWSFMRSZ855xw6cJyDS29grtFWprVB7' not contain NodeOwner '3NtNJV44wyxRXv2jyW3yXLxjJxvY1vR88TF'"
}

Примечание

Существуют аналогичные методы для обычных смарт-контрактов: GET /contracts/{contractId} и POST /contracts/{contractId}.

GET /confidential-contracts/tx/{executable-tx-id}

Метод возвращает транзакцию записи результата исполнения конфиденциального смарт-контракта в его стейт (105.ExecutedContract версии 4), конфиденциальные входные данные для запуска контракта (ConfidentialInput) и конфиденциальные результаты исполнения контракта (ConfidentialOutput) участникам соответствующей политики (группы авторизации).

В свою очередь, транзакция 105.ExecutedContract содержит все поля транзакций 103. CreateContract, 104. CallContract, 107. UpdateContract смарт-контракта.

Важно

Вызов метода GET /confidential-contracts/tx/{executable-tx-id} доступен только участникам соответствующей политики при использовании oAuth токена с ролью ConfidentialContractUser или специального api-key.

Пример ответа для участников политики:

GET /confidential-contracts/tx/{executable-tx-id}:
{
  "executedContractTransactionV4": {
    "senderPublicKey": "4nYb9pKHjndhCkCSCLFoP5GXwH8VTNNyzduFDShUtpD9",
    "tx": {
      "senderPublicKey": "CgqRPcPnexY533gCh2SSvBXh5bca1qMs7KFGntawHGww",
      "inputCommitment": "Ee35NnBwJNQTEhMv4m2EgpjgLj99sr1fVzEukVS7PuCS",
      "fee": 10000000,
      "payments": [],
      "type": 104,
      "params": [],
      "version": 6,
      "contractVersion": 1,
      "atomicBadge": null,
      "sender": "3NkZd8Xd4KsuPiNVsuphRNCZE3SqJycqv8d",
      "feeAssetId": null,
      "proofs": [
        "26sgy8uvZNLk3ePCp99MB6NkuzUPG3rLTZ1Hx63nMCsGsS1MzRsGDy5dmqWgFJBsSmYhNuYGY8KQnrSaMvWdqDw3"
      ],
      "contractId": "9KkLSJA8zXKtnCWSFMRSZ855xw6cJyDS29grtFWprVB7",
      "id": "8HBTx3CZxzWusLY1Fp55HER7jAA9aQfucKJTTMbkfSc7",
      "timestamp": 1704835802000
    },
    "resultsHash": "DsHN64QHaf3SwNz13smhPjx6hHX1sCArbjCfrfWGtVJq",
    "fee": 0,
    "validationProofs": [],
    "type": 105,
    "version": 4,
    "outputCommitment": "FwK5BbtHoQKo6r9uUaBPLYziV4j9YMKXQAAS4NMpqrWZ",
    "readings": [],
    "sender": "3NqTPTybHjETw2g37vee4WuYjdB6rje1mNa",
    "assetOperations": [],
    "proofs": [
      "2YKSvZXMj5zQXxhg9b8RGFQpHGxLDXKLiX3jHGs84xbcQN82yDLHEJRGgniyY88EWUgoR1sD94iRnoQNoMGshUge"
    ],
    "id": "Gv2dzpWyXrDoH1DE9yDSz5sHu81jEwLLGm47vCuQZef3",
    "results": [],
    "readingsHash": null,
    "timestamp": 1704835803181
  },
  "confidentialInput": {
    "commitment": "Ee35NnBwJNQTEhMv4m2EgpjgLj99sr1fVzEukVS7PuCS",
    "txId": "8HBTx3CZxzWusLY1Fp55HER7jAA9aQfucKJTTMbkfSc7",
    "contractId": {
      "byteStr": "9KkLSJA8zXKtnCWSFMRSZ855xw6cJyDS29grtFWprVB7"
    },
    "commitmentKey": {
      "bytes": "9PshLtfpaKGDaxkHSGS6JjKRMRmFwSEg84aJPS9FiZdj"
    },
    "entries": [
      {
        "type": "integer",
        "value": 1,
        "key": "COUNTERS_COUNT"
      }
    ]
  },
  "confidentialOutput": {
    "commitment": "FwK5BbtHoQKo6r9uUaBPLYziV4j9YMKXQAAS4NMpqrWZ",
    "txId": "8HBTx3CZxzWusLY1Fp55HER7jAA9aQfucKJTTMbkfSc7",
    "contractId": {
      "byteStr": "9KkLSJA8zXKtnCWSFMRSZ855xw6cJyDS29grtFWprVB7"
    },
    "commitmentKey": {
      "bytes": "9PshLtfpaKGDaxkHSGS6JjKRMRmFwSEg84aJPS9FiZdj"
    },
    "entries": [
      {
        "type": "integer",
        "value": 1,
        "key": "sum"
      }
    ]
  }
}

Пример ответа для адреса, который не является участником политики:

GET /confidential-contracts/tx/{executable-tx-id}:
{
  "error": 199,
  "message": "Node owner with address '3NtNJV44wyxRXv2jyW3yXLxjJxvY1vR88TF' is not in confidential groups for contract with id: '9KkLSJA8zXKtnCWSFMRSZ855xw6cJyDS29grtFWprVB7'"
}

Примечание

Существует аналогичный метод для обычных смарт-контрактов: GET /contracts/executed-tx-for/{id}.

Смотрите также

Методы REST API

Конфиденциальные смарт-контракты

Смарт-контракты

Разработка и применение смарт-контрактов