shgraph.hedera-protobuf-java-api.0.56.2.source-code.consensus_service.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.1
Show 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);
}