/**
 * # Create Topic
 * Create a new topic for the Hedera Consensus Service (HCS).
 *
 * ### Keywords
 * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 * document are to be interpreted as described in
 * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in
 * [RFC8174](https://www.ietf.org/rfc/rfc8174).
 */
syntax = "proto3";

package proto;

/*
 * Copyright (C) 2018-2024 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.api.proto.java";
// <<<pbj.java_package = "com.hedera.hapi.node.consensus">>> This comment is special code for setting PBJ Compiler java package
option java_multiple_files = true;

import "basic_types.proto";
import "custom_fees.proto";
import "duration.proto";

/**
 * Create a topic to accept and group consensus messages.
 *
 * If `autoRenewAccount` is specified, that account Key MUST also sign this
 * transaction.<br/>
 * If `adminKey` is set, that Key MUST sign the transaction.<br/>
 * On success, the resulting `TransactionReceipt` SHALL contain the newly
 * created `TopicId`.
 *
 * The `autoRenewPeriod` on a topic MUST be set to a value between
 * `autoRenewPeriod.minDuration` and `autoRenewPeriod.maxDuration`. These
 * values are configurable, typically 30 and 92 days.<br/>
 * This also sets the initial expirationTime of the topic.
 *
 * If no `adminKey` is set on a topic
 *   -`autoRenewAccount` SHALL NOT be set on the topic.
 *   - A `deleteTopic` transaction SHALL fail.
 *   - An `updateTopic` transaction that only extends the expirationTime MAY
 *     succeed.
 *   - Any other `updateTopic` transaction SHALL fail.
 *
 * If the topic expires and is not automatically renewed, the topic SHALL enter
 * the `EXPIRED` state.
 *   - All transactions on the topic SHALL fail with TOPIC_EXPIRED
 *      - Except an updateTopic() call that only extends the expirationTime.
 *   - getTopicInfo() SHALL succeed, and show the topic is expired.
 * The topic SHALL remain in the `EXPIRED` state for a time determined by the
 * `autorenew.gracePeriod` (configurable, originally 7 days).<br/>
 * After the grace period, if the topic's expirationTime is not extended, the
 * topic SHALL be automatically deleted from state entirely, and cannot be
 * recovered or recreated.
 *
 * ### Block Stream Effects
 * None
 */
message ConsensusCreateTopicTransactionBody {
    /**
     * A short memo for this topic.
     * <p>
     * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes`
     * (default 100) bytes when encoded as UTF-8.
     */
    string memo = 1;

    /**
     * Access control for modification of the topic after it is created.
     * <p>
     * If this field is set, that key MUST sign this transaction.<br/>
     * If this field is set, that key MUST sign each future transaction to
     * update or delete the topic.<br/>
     * An updateTopic transaction that _only_ extends the topic expirationTime
     * (a "manual renewal" transaction) SHALL NOT require admin key
     * signature.<br/>
     * A topic without an admin key SHALL be immutable, except for expiration
     * and renewal.<br/>
     * If adminKey is not set, then `autoRenewAccount` SHALL NOT be set.
     */
    Key adminKey = 2;

    /**
     * Access control for message submission to the topic.
     * <p>
     * If this field is set, that key MUST sign each consensus submit message
     * for this topic.<br/>
     * If this field is not set then any account may submit a message on the
     * topic, without restriction.
     */
    Key submitKey = 3;

    /**
     * The initial lifetime, in seconds, for the topic.<br/>
     * This is also the number of seconds for which the topic SHALL be
     * automatically renewed upon expiring, if it has a valid auto-renew
     * account.
     * <p>
     * This value MUST be set.<br/>
     * This value MUST be greater than the configured
     * MIN_AUTORENEW_PERIOD.<br/>
     * This value MUST be less than the configured MAX_AUTORENEW_PERIOD.
     */
    Duration autoRenewPeriod = 6;

    /**
     * The ID of the account to be charged renewal fees at the topic's
     * expirationTime to extend the lifetime of the topic.
     * <p>
     * The topic lifetime SHALL be extended by the smallest of the following:
     * <ul>
     *   <li>The current `autoRenewPeriod` duration.</li>
     *   <li>The maximum duration that this account has funds to purchase.</li>
     *   <li>The configured MAX_AUTORENEW_PERIOD at the time of automatic
     *       renewal.</li>
     * </ul>
     * If this value is set, the referenced account MUST sign this
     * transaction.<br/>
     * If this value is set, the `adminKey` field MUST also be set (though that
     * key MAY not have any correlation to this account).
     */
    AccountID autoRenewAccount = 7;

    /**
     * Access control for update or delete of custom fees.
     * <p>
     * If set, subsequent `consensus_update_topic` transactions signed with this
     * key MAY update or delete the custom fees for this topic.<br/>
     * If not set, the custom fees for this topic SHALL BE immutable.<br/>
     * If not set when the topic is created, this field CANNOT be set via
     * update.<br/>
     * If set when the topic is created, this field MAY be changed via update.
     */
    Key fee_schedule_key = 8;

    /**
     * A set of keys.<br/>
     * Keys in this list are permitted to submit messages to this topic without
     * paying custom fees associated with this topic.
     * <p>
     * If a submit transaction is signed by _any_ key included in this set,
     * custom fees SHALL NOT be charged for that transaction.<br/>
     * This field MUST NOT contain more than 10 keys.<br/>
     * fee_exempt_key_list SHALL NOT contain any duplicate keys.<br/>
     * fee_exempt_key_list MAY contain keys for accounts that are inactive,
     * deleted, or non-existent.<br/>
     * If fee_exempt_key_list is unset in this transaction, there SHALL NOT be
     * any fee-exempt keys.  In particular, the following keys SHALL NOT be
     * implicitly or automatically added to this list:
     * `adminKey`, `submitKey`, `fee_schedule_key`.
     */
    repeated Key fee_exempt_key_list = 9;

    /**
     * A set of custom fee definitions.<br/>
     * These are fees to be assessed for each submit to this topic.
     * <p>
     * Each fee defined in this set SHALL be evaluated for
     * each message submitted to this topic, and the resultant
     * total assessed fees SHALL be charged.<br/>
     * Custom fees defined here SHALL be assessed in addition to the base
     * network and node fees.<br/>
     * custom_fees list SHALL NOT contain more than
     * `MAX_CUSTOM_FEE_ENTRIES_FOR_TOPICS` entries.
     */
    repeated FixedCustomFee custom_fees = 10;
}