shgraph.hapi.0.54.0.source-code.consensus_service.proto Maven / Gradle / Ivy
The newest version!
syntax = "proto3";
package proto;
/*-
*
* Hedera Network Services Protobuf
*
* Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
option java_package = "com.hederahashgraph.service.proto.java";
// <<>> This comment is special code for setting PBJ Compiler java package
import "query.proto";
import "response.proto";
import "transaction_response.proto";
import "transaction.proto";
/**
* The Consensus Service provides the ability for Hedera Hashgraph to provide aBFT consensus as to
* the order and validity of messages submitted to a *topic*, as well as a *consensus timestamp* for
* those messages.
*
* Automatic renewal can be configured via an autoRenewAccount.
* Any time an autoRenewAccount is added to a topic, that createTopic/updateTopic transaction must
* be signed by the autoRenewAccount.
*
* The autoRenewPeriod on an account must currently be set a value in createTopic between
* MIN_AUTORENEW_PERIOD (6999999 seconds) and MAX_AUTORENEW_PERIOD (8000001 seconds). During
* creation this sets the initial expirationTime of the topic (see more below).
*
* If no adminKey is on a topic, there may not be an autoRenewAccount on the topic, deleteTopic is
* not allowed, and the only change allowed via an updateTopic is to extend the expirationTime.
*
* If an adminKey is on a topic, every updateTopic and deleteTopic transaction must be signed by the
* adminKey, except for updateTopics which only extend the topic's expirationTime (no adminKey
* authorization required).
*
* If an updateTopic modifies the adminKey of a topic, the transaction signatures on the updateTopic
* must fulfill both the pre-update and post-update adminKey signature requirements.
*
* Mirrornet ConsensusService may be used to subscribe to changes on the topic, including changes to
* the topic definition and the consensus ordering and timestamp of submitted messages.
*
* Until autoRenew functionality is supported by HAPI, the topic will not expire, the
* autoRenewAccount will not be charged, and the topic will not automatically be deleted.
*
* Once autoRenew functionality is supported by HAPI:
*
* 1. Once the expirationTime is encountered, if an autoRenewAccount is configured on the topic, the
* account will be charged automatically at the expirationTime, to extend the expirationTime of the
* topic up to the topic's autoRenewPeriod (or as much extension as the account's balance will
* supply).
*
* 2. If the topic expires and is not automatically renewed, the topic will enter the EXPIRED state.
* All transactions on the topic will fail with TOPIC_EXPIRED, except an updateTopic() call that
* modifies only the expirationTime. getTopicInfo() will succeed. This state will be available for
* a AUTORENEW_GRACE_PERIOD grace period (7 days).
*
* 3. After the grace period, if the topic's expirationTime is not extended, the topic will be
* automatically deleted and no transactions or queries on the topic will succeed after that point.
*/
service ConsensusService {
/**
* Create a topic to be used for consensus.
* If an autoRenewAccount is specified, that account must also sign this transaction.
* If an adminKey is specified, the adminKey must sign the transaction.
* On success, the resulting TransactionReceipt contains the newly created TopicId.
* Request is [ConsensusCreateTopicTransactionBody](#proto.ConsensusCreateTopicTransactionBody)
*/
rpc createTopic (Transaction) returns (TransactionResponse);
/**
* Update a topic.
* If there is no adminKey, the only authorized update (available to anyone) is to extend the expirationTime.
* Otherwise transaction must be signed by the adminKey.
* If an adminKey is updated, the transaction must be signed by the pre-update adminKey and post-update adminKey.
* If a new autoRenewAccount is specified (not just being removed), that account must also sign the transaction.
* Request is [ConsensusUpdateTopicTransactionBody](#proto.ConsensusUpdateTopicTransactionBody)
*/
rpc updateTopic (Transaction) returns (TransactionResponse);
/**
* Delete a topic. No more transactions or queries on the topic (via HAPI) will succeed.
* If an adminKey is set, this transaction must be signed by that key.
* If there is no adminKey, this transaction will fail UNAUTHORIZED.
* Request is [ConsensusDeleteTopicTransactionBody](#proto.ConsensusDeleteTopicTransactionBody)
*/
rpc deleteTopic (Transaction) returns (TransactionResponse);
/**
* Retrieve the latest state of a topic. This method is unrestricted and allowed on any topic by any payer account.
* Deleted accounts will not be returned.
* Request is [ConsensusGetTopicInfoQuery](#proto.ConsensusGetTopicInfoQuery)
* Response is [ConsensusGetTopicInfoResponse](#proto.ConsensusGetTopicInfoResponse)
*/
rpc getTopicInfo (Query) returns (Response);
/**
* Submit a message for consensus.
* Valid and authorized messages on valid topics will be ordered by the consensus service, gossipped to the
* mirror net, and published (in order) to all subscribers (from the mirror net) on this topic.
* The submitKey (if any) must sign this transaction.
* On success, the resulting TransactionReceipt contains the topic's updated topicSequenceNumber and
* topicRunningHash.
* Request is [ConsensusSubmitMessageTransactionBody](#proto.ConsensusSubmitMessageTransactionBody)
*/
rpc submitMessage (Transaction) returns (TransactionResponse);
}