shgraph.hedera-protobuf-java-api.0.10.0.source-code.ConsensusService.proto Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of hedera-protobuf-java-api Show documentation
Hedera Protobuf Java API
There is a newer version: 0.57.3
Show newest version
syntax = "proto3";

package proto;

/*-
 * ‌
 * Hedera Network Services Protobuf
 * 
 * Copyright (C) 2018 - 2020 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";

import "Query.proto";
import "Response.proto";
import "TransactionResponse.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);
}