diff --git a/mirror/consensus_service.proto b/mirror/consensus_service.proto index d9f2a76a..438633e2 100644 --- a/mirror/consensus_service.proto +++ b/mirror/consensus_service.proto @@ -22,7 +22,11 @@ syntax = "proto3"; package com.hedera.mirror.api.proto; -option java_multiple_files = true; // Required for the reactor-grpc generator to work correctly +/** + * Required for the reactor-grpc generator to work correctly + */ +option java_multiple_files = true; + option java_package = "com.hedera.mirror.api.proto"; import "basic_types.proto"; @@ -30,38 +34,67 @@ import "timestamp.proto"; import "consensus_submit_message.proto"; message ConsensusTopicQuery { - .proto.TopicID topicID = 1; // A required topic ID to retrieve messages for. + /** + * A required topic ID to retrieve messages for. + */ + .proto.TopicID topicID = 1; - // Include messages which reached consensus on or after this time. Defaults to current time if not set. + /** + * Include messages which reached consensus on or after this time. Defaults to current time if + * not set. + */ .proto.Timestamp consensusStartTime = 2; - // Include messages which reached consensus before this time. If not set it will receive indefinitely. + /** + * Include messages which reached consensus before this time. If not set it will receive + * indefinitely. + */ .proto.Timestamp consensusEndTime = 3; - // The maximum number of messages to receive before stopping. If not set or set to zero it will return messages - // indefinitely. + /** + * The maximum number of messages to receive before stopping. If not set or set to zero it will + * return messages indefinitely. + */ uint64 limit = 4; } message ConsensusTopicResponse { - .proto.Timestamp consensusTimestamp = 1; // The time at which the transaction reached consensus + /** + * The time at which the transaction reached consensus + */ + .proto.Timestamp consensusTimestamp = 1; - // The message body originally in the ConsensusSubmitMessageTransactionBody. Message size will be less than 6KiB. + /** + * The message body originally in the ConsensusSubmitMessageTransactionBody. Message size will + * be less than 6KiB. + */ bytes message = 2; - bytes runningHash = 3; // The running hash (SHA384) of every message. + /** + * The running hash (SHA384) of every message. + */ + bytes runningHash = 3; - uint64 sequenceNumber = 4; // Starts at 1 for first submitted message. Incremented on each submitted message. + /** + * Starts at 1 for first submitted message. Incremented on each submitted message. + */ + uint64 sequenceNumber = 4; - uint64 runningHashVersion = 5; // Version of the SHA-384 digest used to update the running hash. + /** + * Version of the SHA-384 digest used to update the running hash. + */ + uint64 runningHashVersion = 5; - .proto.ConsensusMessageChunkInfo chunkInfo = 6; // Optional information of the current chunk in a fragmented message. + /** + * Optional information of the current chunk in a fragmented message. + */ + .proto.ConsensusMessageChunkInfo chunkInfo = 6; } -// -// The Mirror Service provides the ability to query a stream of Hedera Consensus Service (HCS) messages for an -// HCS Topic via a specific (possibly open-ended) time range. -// +/** + * The Mirror Service provides the ability to query a stream of Hedera Consensus Service (HCS) + * messages for an HCS Topic via a specific (possibly open-ended) time range. + */ service ConsensusService { rpc subscribeTopic (ConsensusTopicQuery) returns (stream ConsensusTopicResponse); } diff --git a/services/basic_types.proto b/services/basic_types.proto index f2dbdc1c..ef7156b3 100644 --- a/services/basic_types.proto +++ b/services/basic_types.proto @@ -27,119 +27,303 @@ import "timestamp.proto"; option java_package = "com.hederahashgraph.api.proto.java"; option java_multiple_files = true; -/* Each shard has a nonnegative shard number. Each realm within a given shard has a nonnegative realm number (that number might be reused in other shards). And each account, file, and smart contract instance within a given realm has a nonnegative number (which might be reused in other realms). Every account, file, and smart contract instance is within exactly one realm. So a FileID is a triplet of numbers, like 0.1.2 for entity number 2 within realm 1 within shard 0. Each realm maintains a single counter for assigning numbers, so if there is a file with ID 0.1.2, then there won't be an account or smart contract instance with ID 0.1.2. - - Everything is partitioned into realms so that each Solidity smart contract can access everything in just a single realm, locking all those entities while it's running, but other smart contracts could potentially run in other realms in parallel. So realms allow Solidity to be parallelized somewhat, even though the language itself assumes everything is serial. */ +/** + * Each shard has a nonnegative shard number. Each realm within a given shard has a nonnegative + * realm number (that number might be reused in other shards). And each account, file, and smart + * contract instance within a given realm has a nonnegative number (which might be reused in other + * realms). Every account, file, and smart contract instance is within exactly one realm. So a + * FileID is a triplet of numbers, like 0.1.2 for entity number 2 within realm 1 within shard 0. + * Each realm maintains a single counter for assigning numbers, so if there is a file with ID + * 0.1.2, then there won't be an account or smart contract instance with ID 0.1.2. + * + * Everything is partitioned into realms so that each Solidity smart contract can access everything + * in just a single realm, locking all those entities while it's running, but other smart contracts + * could potentially run in other realms in parallel. So realms allow Solidity to be parallelized + * somewhat, even though the language itself assumes everything is serial. + */ message ShardID { - int64 shardNum = 1; //the shard number (nonnegative) + /** + * the shard number (nonnegative) + */ + int64 shardNum = 1; } -/* The ID for a realm. Within a given shard, every realm has a unique ID. Each account, file, and contract instance belongs to exactly one realm. */ +/** + * The ID for a realm. Within a given shard, every realm has a unique ID. Each account, file, and + * contract instance belongs to exactly one realm. + */ message RealmID { - int64 shardNum = 1; //The shard number (nonnegative) - int64 realmNum = 2; //The realm number (nonnegative) + /** + * The shard number (nonnegative) + */ + int64 shardNum = 1; + + /** + * The realm number (nonnegative) + */ + int64 realmNum = 2; } -/* The ID for an a cryptocurrency account */ +/** + * The ID for an a cryptocurrency account + */ message AccountID { - int64 shardNum = 1; //The shard number (nonnegative) - int64 realmNum = 2; //The realm number (nonnegative) - int64 accountNum = 3; //A nonnegative account number unique within its realm + /** + * The shard number (nonnegative) + */ + int64 shardNum = 1; + + /** + * The realm number (nonnegative) + */ + int64 realmNum = 2; + + /** + * A nonnegative account number unique within its realm + */ + int64 accountNum = 3; } -/* The ID for a file */ +/** + * The ID for a file + */ message FileID { - int64 shardNum = 1; //The shard number (nonnegative) - int64 realmNum = 2; //The realm number (nonnegative) - int64 fileNum = 3; //A nonnegative File number unique within its realm + /** + * The shard number (nonnegative) + */ + int64 shardNum = 1; + + /** + * The realm number (nonnegative) + */ + int64 realmNum = 2; + + /** + * A nonnegative File number unique within its realm + */ + int64 fileNum = 3; } -/* The ID for a smart contract instance */ +/** + * The ID for a smart contract instance + */ message ContractID { - int64 shardNum = 1; //The shard number (nonnegative) - int64 realmNum = 2; //The realm number (nonnegative) - int64 contractNum = 3; //A nonnegative number unique within its realm -} - -/* -The ID for a transaction. This is used for retrieving receipts and records for a transaction, for appending to a file right after creating it, for instantiating a smart contract with bytecode in a file just created, and internally by the network for detecting when duplicate transactions are submitted. A user might get a transaction processed faster by submitting it to N nodes, each with a different node account, but all with the same TransactionID. Then, the transaction will take effect when the first of all those nodes submits the transaction and it reaches consensus. The other transactions will not take effect. So this could make the transaction take effect faster, if any given node might be slow. However, the full transaction fee is charged for each transaction, so the total fee is N times as much if the transaction is sent to N nodes. -Applicable to Scheduled Transactions: -- The ID of a Scheduled Transaction has transactionValidStart and accountIDs inherited from the ScheduleCreate transaction that created it. That is to say that they are equal -- The scheduled property is true for Scheduled Transactions -- transactionValidStart, accountID and scheduled properties should be omitted -*/ + /** + * The shard number (nonnegative) + */ + int64 shardNum = 1; + + /** + * The realm number (nonnegative) + */ + int64 realmNum = 2; + + /** + * A nonnegative number unique within its realm + */ + int64 contractNum = 3; +} + +/** + * The ID for a transaction. This is used for retrieving receipts and records for a transaction, for + * appending to a file right after creating it, for instantiating a smart contract with bytecode in + * a file just created, and internally by the network for detecting when duplicate transactions are + * submitted. A user might get a transaction processed faster by submitting it to N nodes, each with + * a different node account, but all with the same TransactionID. Then, the transaction will take + * effect when the first of all those nodes submits the transaction and it reaches consensus. The + * other transactions will not take effect. So this could make the transaction take effect faster, + * if any given node might be slow. However, the full transaction fee is charged for each + * transaction, so the total fee is N times as much if the transaction is sent to N nodes. + * + * Applicable to Scheduled Transactions: + * - The ID of a Scheduled Transaction has transactionValidStart and accountIDs inherited from the + * ScheduleCreate transaction that created it. That is to say that they are equal + * - The scheduled property is true for Scheduled Transactions + * - transactionValidStart, accountID and scheduled properties should be omitted + */ message TransactionID { - Timestamp transactionValidStart = 1; // The transaction is invalid if consensusTimestamp < transactionID.transactionStartValid - AccountID accountID = 2; // The Account ID that paid for this transaction - bool scheduled = 3; // Whether the Transaction is of type Scheduled or no + /** + * The transaction is invalid if consensusTimestamp < transactionID.transactionStartValid + */ + Timestamp transactionValidStart = 1; + + /** + * The Account ID that paid for this transaction + */ + AccountID accountID = 2; + + /** + * Whether the Transaction is of type Scheduled or no + */ + bool scheduled = 3; } -/* An account, and the amount that it sends or receives during a cryptocurrency or token transfer. */ +/** + * An account, and the amount that it sends or receives during a cryptocurrency or token transfer. + */ message AccountAmount { - AccountID accountID = 1; // The Account ID that sends/receives cryptocurrency or tokens - sint64 amount = 2; // The amount of tinybars (for Crypto transfers) or in the lowest denomination (for Token transfers) that the account sends(negative) or receives(positive) + /** + * The Account ID that sends/receives cryptocurrency or tokens + */ + AccountID accountID = 1; + + /** + * The amount of tinybars (for Crypto transfers) or in the lowest + * denomination (for Token transfers) that the account sends(negative) or + * receives(positive) + */ + sint64 amount = 2; } -/* A list of accounts and amounts to transfer out of each account (negative) or into it (positive). */ +/** + * A list of accounts and amounts to transfer out of each account (negative) or into it (positive). + */ message TransferList { - repeated AccountAmount accountAmounts = 1; // Multiple list of AccountAmount pairs, each of which has an account and an amount to transfer into it (positive) or out of it (negative) + /** + * Multiple list of AccountAmount pairs, each of which has an account and + * an amount to transfer into it (positive) or out of it (negative) + */ + repeated AccountAmount accountAmounts = 1; } -/* A sender account, a receiver account, and the serial number of an NFT of a Token with NON_FUNGIBLE_UNIQUE type. When minting NFTs the sender will be the default AccountID instance (0.0.0) and when burning NFTs, the receiver will be the default AccountID instance. */ +/** + * A sender account, a receiver account, and the serial number of an NFT of a Token with + * NON_FUNGIBLE_UNIQUE type. When minting NFTs the sender will be the default AccountID instance + * (0.0.0) and when burning NFTs, the receiver will be the default AccountID instance. + */ message NftTransfer { - AccountID senderAccountID = 1; // The accountID of the sender - AccountID receiverAccountID = 2; // The accountID of the receiver - int64 serialNumber = 3; // The serial number of the NFT + /** + * The accountID of the sender + */ + AccountID senderAccountID = 1; + + /** + * The accountID of the receiver + */ + AccountID receiverAccountID = 2; + + /** + * The serial number of the NFT + */ + int64 serialNumber = 3; } -/* A list of token IDs and amounts representing the transferred out (negative) or into (positive) amounts, represented in the lowest denomination of the token */ +/** + * A list of token IDs and amounts representing the transferred out (negative) or into (positive) + * amounts, represented in the lowest denomination of the token + */ message TokenTransferList { - TokenID token = 1; // The ID of the token - repeated AccountAmount transfers = 2; // Applicable to tokens of type FUNGIBLE_COMMON. Multiple list of AccountAmounts, each of which has an account and amount - repeated NftTransfer nftTransfers = 3; // Applicable to tokens of type NON_FUNGIBLE_UNIQUE. Multiple list of NftTransfers, each of which has a sender and receiver account, including the serial number of the NFT + /** + * The ID of the token + */ + TokenID token = 1; + + /** + * Applicable to tokens of type FUNGIBLE_COMMON. Multiple list of AccountAmounts, each of which + * has an account and amount + */ + repeated AccountAmount transfers = 2; + + /** + * Applicable to tokens of type NON_FUNGIBLE_UNIQUE. Multiple list of NftTransfers, each of + * which has a sender and receiver account, including the serial number of the NFT + */ + repeated NftTransfer nftTransfers = 3; } -/* A rational number, used to set the amount of a value transfer to collect as a custom fee */ +/** + * A rational number, used to set the amount of a value transfer to collect as a custom fee + */ message Fraction { - int64 numerator = 1; // The rational's numerator - int64 denominator = 2; // The rational's denominator; a zero value will result in FRACTION_DIVIDES_BY_ZERO + /** + * The rational's numerator + */ + int64 numerator = 1; + + /** + * The rational's denominator; a zero value will result in FRACTION_DIVIDES_BY_ZERO + */ + int64 denominator = 2; } -/* Unique identifier for a topic (used by the consensus service) */ +/** + * Unique identifier for a topic (used by the consensus service) + */ message TopicID { - int64 shardNum = 1; // The shard number (nonnegative) - int64 realmNum = 2; // The realm number (nonnegative) - int64 topicNum = 3; // Unique topic identifier within a realm (nonnegative). + /** + * The shard number (nonnegative) + */ + int64 shardNum = 1; + + /** + * The realm number (nonnegative) + */ + int64 realmNum = 2; + + /** + * Unique topic identifier within a realm (nonnegative). + */ + int64 topicNum = 3; } -/* Unique identifier for a token */ +/** + * Unique identifier for a token + */ message TokenID { - int64 shardNum = 1; // A nonnegative shard number - int64 realmNum = 2; // A nonnegative realm number - int64 tokenNum = 3; // A nonnegative token number + /** + * A nonnegative shard number + */ + int64 shardNum = 1; + + /** + * A nonnegative realm number + */ + int64 realmNum = 2; + + /** + * A nonnegative token number + */ + int64 tokenNum = 3; } -/* Unique identifier for a Schedule */ +/** + * Unique identifier for a Schedule + */ message ScheduleID { - int64 shardNum = 1; // A nonnegative shard number - int64 realmNum = 2; // A nonnegative realm number - int64 scheduleNum = 3; // A nonnegative schedule number + /** + * A nonnegative shard number + */ + int64 shardNum = 1; + + /** + * A nonnegative realm number + */ + int64 realmNum = 2; + + /** + * A nonnegative schedule number + */ + int64 scheduleNum = 3; } /** * Possible Token Types (IWA Compatibility). - * Apart from fungible and non-fungible, Tokens can have either a common or unique representation. This distinction might seem subtle, but it is important when considering - * how tokens can be traced and if they can have isolated and unique properties. + * Apart from fungible and non-fungible, Tokens can have either a common or unique representation. + * This distinction might seem subtle, but it is important when considering how tokens can be traced + * and if they can have isolated and unique properties. */ enum TokenType { /** - * Interchangeable value with one another, where any quantity of them has the same value as another equal quantity if they are in the same class. - * Share a single set of properties, not distinct from one another. Simply represented as a balance or quantity to a given Hedera account. + * Interchangeable value with one another, where any quantity of them has the same value as + * another equal quantity if they are in the same class. Share a single set of properties, not + * distinct from one another. Simply represented as a balance or quantity to a given Hedera + * account. */ FUNGIBLE_COMMON = 0; + /** - * Unique, not interchangeable with other tokens of the same type as they typically have different values. - * Individually traced and can carry unique properties (e.g. serial number). + * Unique, not interchangeable with other tokens of the same type as they typically have + * different values. Individually traced and can carry unique properties (e.g. serial number). */ NON_FUNGIBLE_UNIQUE = 1; } @@ -147,20 +331,41 @@ enum TokenType { /** * Allows a set of resource prices to be scoped to a certain type of a HAPI operation. * - * For example, the resource prices for a TokenMint operation are different between - * minting fungible and non-fungible tokens. This enum allows us to "mark" a set of - * prices as applying to one or the other. + * For example, the resource prices for a TokenMint operation are different between minting fungible + * and non-fungible tokens. This enum allows us to "mark" a set of prices as applying to one or the + * other. * - * Similarly, the resource prices for a basic TokenCreate without a custom fee schedule - * yield a total price of $1. The resource prices for a TokenCreate with a custom fee - * schedule are different and yield a total base price of $2. + * Similarly, the resource prices for a basic TokenCreate without a custom fee schedule yield a + * total price of $1. The resource prices for a TokenCreate with a custom fee schedule are different + * and yield a total base price of $2. */ enum SubType { - DEFAULT = 0; // The resource prices have no special scope - TOKEN_FUNGIBLE_COMMON = 1; // The resource prices are scoped to an operation on a fungible common token - TOKEN_NON_FUNGIBLE_UNIQUE = 2; // The resource prices are scoped to an operation on a non-fungible unique token - TOKEN_FUNGIBLE_COMMON_WITH_CUSTOM_FEES = 3; // The resource prices are scoped to an operation on a fungible common token with a custom fee schedule - TOKEN_NON_FUNGIBLE_UNIQUE_WITH_CUSTOM_FEES = 4; // The resource prices are scoped to an operation on a non-fungible unique token with a custom fee schedule + /** + * The resource prices have no special scope + */ + DEFAULT = 0; + + /** + * The resource prices are scoped to an operation on a fungible common token + */ + TOKEN_FUNGIBLE_COMMON = 1; + + /** + * The resource prices are scoped to an operation on a non-fungible unique token + */ + TOKEN_NON_FUNGIBLE_UNIQUE = 2; + + /** + * The resource prices are scoped to an operation on a fungible common + * token with a custom fee schedule + */ + TOKEN_FUNGIBLE_COMMON_WITH_CUSTOM_FEES = 3; + + /** + * The resource prices are scoped to an operation on a non-fungible unique + * token with a custom fee schedule + */ + TOKEN_NON_FUNGIBLE_UNIQUE_WITH_CUSTOM_FEES = 4; } /** @@ -168,327 +373,998 @@ enum SubType { * Indicates how many tokens can have during its lifetime. */ enum TokenSupplyType { - INFINITE = 0; // Indicates that tokens of that type have an upper bound of Long.MAX_VALUE. - FINITE = 1; // Indicates that tokens of that type have an upper bound of maxSupply, provided on token creation. + /** + * Indicates that tokens of that type have an upper bound of Long.MAX_VALUE. + */ + INFINITE = 0; + + /** + * Indicates that tokens of that type have an upper bound of maxSupply, + * provided on token creation. + */ + FINITE = 1; } -/* Possible Freeze statuses returned on TokenGetInfoQuery or CryptoGetInfoResponse in TokenRelationship */ +/** + * Possible Freeze statuses returned on TokenGetInfoQuery or CryptoGetInfoResponse in + * TokenRelationship + */ enum TokenFreezeStatus { + /** + * UNDOCUMENTED + */ FreezeNotApplicable = 0; + + /** + * UNDOCUMENTED + */ Frozen = 1; + + /** + * UNDOCUMENTED + */ Unfrozen = 2; } -/* Possible KYC statuses returned on TokenGetInfoQuery or CryptoGetInfoResponse in TokenRelationship */ +/** + * Possible KYC statuses returned on TokenGetInfoQuery or CryptoGetInfoResponse in TokenRelationship + */ enum TokenKycStatus { + /** + * UNDOCUMENTED + */ KycNotApplicable = 0; + + /** + * UNDOCUMENTED + */ Granted = 1; + + /** + * UNDOCUMENTED + */ Revoked = 2; } -/* A Key can be a public key from one of the three supported systems (ed25519, RSA-3072, ECDSA with p384). Or, it can be the ID of a smart contract instance, which is authorized to act as if it had a key. If an account has an ed25519 key associated with it, then the corresponding private key must sign any transaction to transfer cryptocurrency out of it. And similarly for RSA and ECDSA. +/** + * A Key can be a public key from one of the three supported systems (ed25519, RSA-3072, ECDSA with + * p384). Or, it can be the ID of a smart contract instance, which is authorized to act as if it had + * a key. If an account has an ed25519 key associated with it, then the corresponding private key + * must sign any transaction to transfer cryptocurrency out of it. And similarly for RSA and ECDSA. * - * A Key can be a smart contract ID, which means that smart contract is to authorize operations as if it had signed with a key that it owned. The smart contract doesn't actually have a key, and doesn't actually sign a transaction. But it's as if a virtual transaction were created, and the smart contract signed it with a private key. + * A Key can be a smart contract ID, which means that smart contract is to authorize operations as + * if it had signed with a key that it owned. The smart contract doesn't actually have a key, and + * doesn't actually sign a transaction. But it's as if a virtual transaction were created, and the + * smart contract signed it with a private key. * - * A Key can be a "threshold key", which means a list of M keys, any N of which must sign in order for the threshold signature to be considered valid. The keys within a threshold signature may themselves be threshold signatures, to allow complex signature requirements. + * A Key can be a "threshold key", which means a list of M keys, any N of which must sign in order + * for the threshold signature to be considered valid. The keys within a threshold signature may + * themselves be threshold signatures, to allow complex signature requirements. * - *A Key can be a "key list" where all keys in the list must sign unless specified otherwise in the documentation for a specific transaction type (e.g. FileDeleteTransactionBody). Their use is dependent on context. For example, a Hedera file is created with a list of keys, where all of them must sign a transaction to create or modify the file, but only one of them is needed to sign a transaction to delete the file. So it's a single list that sometimes acts as a 1-of-M threshold key, and sometimes acts as an M-of-M threshold key. A key list is always an M-of-M, unless specified otherwise in documentation. A key list can have nested key lists or threshold keys. Nested key lists are always M-of-M. A key list can have repeated Ed25519 public keys, but all repeated keys are only required to sign once. + * A Key can be a "key list" where all keys in the list must sign unless specified otherwise in the + * documentation for a specific transaction type (e.g. FileDeleteTransactionBody). Their use is + * dependent on context. For example, a Hedera file is created with a list of keys, where all of + * them must sign a transaction to create or modify the file, but only one of them is needed to sign + * a transaction to delete the file. So it's a single list that sometimes acts as a 1-of-M threshold + * key, and sometimes acts as an M-of-M threshold key. A key list is always an M-of-M, unless + * specified otherwise in documentation. A key list can have nested key lists or threshold keys. + * Nested key lists are always M-of-M. A key list can have repeated Ed25519 public keys, but all + * repeated keys are only required to sign once. * - * A Key can contain a ThresholdKey or KeyList, which in turn contain a Key, so this mutual recursion would allow nesting arbitrarily deep. A ThresholdKey which contains a list of primitive keys (e.g., ed25519) has 3 levels: ThresholdKey -> KeyList -> Key. A KeyList which contains several primitive keys (e.g., ed25519) has 2 levels: KeyList -> Key. A Key with 2 levels of nested ThresholdKeys has 7 levels: Key -> ThresholdKey -> KeyList -> Key -> ThresholdKey -> KeyList -> Key. + * A Key can contain a ThresholdKey or KeyList, which in turn contain a Key, so this mutual + * recursion would allow nesting arbitrarily deep. A ThresholdKey which contains a list of primitive + * keys (e.g., ed25519) has 3 levels: ThresholdKey -> KeyList -> Key. A KeyList which contains + * several primitive keys (e.g., ed25519) has 2 levels: KeyList -> Key. A Key with 2 levels of + * nested ThresholdKeys has 7 levels: Key -> ThresholdKey -> KeyList -> Key -> ThresholdKey -> + * KeyList -> Key. * - * Each Key should not have more than 46 levels, which implies 15 levels of nested ThresholdKeys. Only ed25519 primitive keys are currently supported. + * Each Key should not have more than 46 levels, which implies 15 levels of nested ThresholdKeys. + * Only ed25519 primitive keys are currently supported. */ message Key { oneof key { - ContractID contractID = 1; // smart contract instance that is authorized as if it had signed with a key - bytes ed25519 = 2; // ed25519 public key bytes - bytes RSA_3072 = 3; // RSA-3072 public key bytes - bytes ECDSA_384 = 4; // ECDSA with the p-384 curve public key bytes - ThresholdKey thresholdKey = 5; // a threshold N followed by a list of M keys, any N of which are required to form a valid signature - KeyList keyList = 6; // A list of Keys of the Key type. + /** + * smart contract instance that is authorized as if it had signed with a key + */ + ContractID contractID = 1; + + /** + * ed25519 public key bytes + */ + bytes ed25519 = 2; + + /** + * RSA-3072 public key bytes + */ + bytes RSA_3072 = 3; + + /** + * ECDSA with the p-384 curve public key bytes + */ + bytes ECDSA_384 = 4; + + /** + * a threshold N followed by a list of M keys, any N of which are required to form a valid + * signature + */ + ThresholdKey thresholdKey = 5; + + /** + * A list of Keys of the Key type. + */ + KeyList keyList = 6; } } -/* A set of public keys that are used together to form a threshold signature. If the threshold is N and there are M keys, then this is an N of M threshold signature. If an account is associated with ThresholdKeys, then a transaction to move cryptocurrency out of it must be signed by a list of M signatures, where at most M-N of them are blank, and the other at least N of them are valid signatures corresponding to at least N of the public keys listed here. */ +/** + * A set of public keys that are used together to form a threshold signature. If the threshold is N + * and there are M keys, then this is an N of M threshold signature. If an account is associated + * with ThresholdKeys, then a transaction to move cryptocurrency out of it must be signed by a list + * of M signatures, where at most M-N of them are blank, and the other at least N of them are valid + * signatures corresponding to at least N of the public keys listed here. + */ message ThresholdKey { - uint32 threshold = 1; // A valid signature set must have at least this many signatures - KeyList keys = 2; // List of all the keys that can sign + /** + * A valid signature set must have at least this many signatures + */ + uint32 threshold = 1; + + /** + * List of all the keys that can sign + */ + KeyList keys = 2; } -/* A list of keys that requires all keys (M-of-M) to sign unless otherwise specified in documentation. A KeyList may contain repeated keys, but all repeated keys are only required to sign once. */ +/** + * A list of keys that requires all keys (M-of-M) to sign unless otherwise specified in + * documentation. A KeyList may contain repeated keys, but all repeated keys are only required to + * sign once. + */ message KeyList { - repeated Key keys = 1; // list of keys + /** + * list of keys + */ + repeated Key keys = 1; } -/* A Signature corresponding to a Key. It is a sequence of bytes holding a public key signature from one of the three supported systems (ed25519, RSA-3072, ECDSA with p384). Or, it can be a list of signatures corresponding to a single threshold key. Or, it can be the ID of a smart contract instance, which is authorized to act as if it had a key. If an account has an ed25519 key associated with it, then the corresponding private key must sign any transaction to transfer cryptocurrency out of it. If it has a smart contract ID associated with it, then that smart contract is allowed to transfer cryptocurrency out of it. The smart contract doesn't actually have a key, and doesn't actually sign a transaction. But it's as if a virtual transaction were created, and the smart contract signed it with a private key. A key can also be a "threshold key", which means a list of M keys, any N of which must sign in order for the threshold signature to be considered valid. The keys within a threshold signature may themselves be threshold signatures, to allow complex signature requirements (this nesting is not supported in the currently, but will be supported in a future version of API). If a Signature message is missing the "signature" field, then this is considered to be a null signature. That is useful in cases such as threshold signatures, where some of the signatures can be null. - * The definition of Key uses mutual recursion, so it allows nesting that is arbitrarily deep. But the current API only accepts Key messages up to 3 levels deep, such as a list of threshold keys, each of which is a list of primitive keys. Therefore, the matching Signature will have the same limitation. This restriction may be relaxed in future versions of the API, to allow deeper nesting. +/** + * A Signature corresponding to a Key. It is a sequence of bytes holding a public key signature from + * one of the three supported systems (ed25519, RSA-3072, ECDSA with p384). Or, it can be a list of + * signatures corresponding to a single threshold key. Or, it can be the ID of a smart contract + * instance, which is authorized to act as if it had a key. If an account has an ed25519 key + * associated with it, then the corresponding private key must sign any transaction to transfer + * cryptocurrency out of it. If it has a smart contract ID associated with it, then that smart + * contract is allowed to transfer cryptocurrency out of it. The smart contract doesn't actually + * have a key, and doesn't actually sign a transaction. But it's as if a virtual transaction were + * created, and the smart contract signed it with a private key. A key can also be a "threshold + * key", which means a list of M keys, any N of which must sign in order for the threshold signature + * to be considered valid. The keys within a threshold signature may themselves be threshold + * signatures, to allow complex signature requirements (this nesting is not supported in the + * currently, but will be supported in a future version of API). If a Signature message is missing + * the "signature" field, then this is considered to be a null signature. That is useful in cases + * such as threshold signatures, where some of the signatures can be null. The definition of Key + * uses mutual recursion, so it allows nesting that is arbitrarily deep. But the current API only + * accepts Key messages up to 3 levels deep, such as a list of threshold keys, each of which is a + * list of primitive keys. Therefore, the matching Signature will have the same limitation. This + * restriction may be relaxed in future versions of the API, to allow deeper nesting. + * * This message is deprecated and succeeded by SignaturePair and SignatureMap messages. */ message Signature { option deprecated = true; + oneof signature { - bytes contract = 1; // smart contract virtual signature (always length zero) - bytes ed25519 = 2; // ed25519 signature bytes - bytes RSA_3072 = 3; //RSA-3072 signature bytes - bytes ECDSA_384 = 4; //ECDSA p-384 signature bytes - ThresholdSignature thresholdSignature = 5; // A list of signatures for a single N-of-M threshold Key. This must be a list of exactly M signatures, at least N of which are non-null. - SignatureList signatureList = 6; // A list of M signatures, each corresponding to a Key in a KeyList of the same length. + /** + * smart contract virtual signature (always length zero) + */ + bytes contract = 1; + + /** + * ed25519 signature bytes + */ + bytes ed25519 = 2; + + /** + * RSA-3072 signature bytes + */ + bytes RSA_3072 = 3; + + /** + * ECDSA p-384 signature bytes + */ + bytes ECDSA_384 = 4; + + /** + * A list of signatures for a single N-of-M threshold Key. This must be a list of exactly M + * signatures, at least N of which are non-null. + */ + ThresholdSignature thresholdSignature = 5; + + /** + * A list of M signatures, each corresponding to a Key in a KeyList of the same length. + */ + SignatureList signatureList = 6; } } -/* -A signature corresponding to a ThresholdKey. For an N-of-M threshold key, this is a list of M signatures, at least N of which must be non-null. -This message is deprecated and succeeded by SignaturePair and SignatureMap messages. -*/ +/** + * A signature corresponding to a ThresholdKey. For an N-of-M threshold key, this is a list of M + * signatures, at least N of which must be non-null. This message is deprecated and succeeded by + * SignaturePair and SignatureMap messages. + */ message ThresholdSignature { option deprecated = true; - SignatureList sigs = 2; // for an N-of-M threshold key, this is a list of M signatures, at least N of which must be non-null + + /** + * for an N-of-M threshold key, this is a list of M signatures, at least N of which must be + * non-null + */ + SignatureList sigs = 2; } -/* -The signatures corresponding to a KeyList of the same length. -This message is deprecated and succeeded by SignaturePair and SignatureMap messages. -*/ +/** + * The signatures corresponding to a KeyList of the same length. This message is deprecated and + * succeeded by SignaturePair and SignatureMap messages. + */ message SignatureList { option deprecated = true; - repeated Signature sigs = 2; // each signature corresponds to a Key in the KeyList + + /** + * each signature corresponds to a Key in the KeyList + */ + repeated Signature sigs = 2; } -/* -The client may use any number of bytes from 0 to the whole length of the public key for pubKeyPrefix. -If 0 bytes is used, then it is assumed that only one public key is used to sign. Only ed25519 -keys and hence signatures are currently supported. */ +/** + * The client may use any number of bytes from 0 to the whole length of the public key for + * pubKeyPrefix. If 0 bytes is used, then it is assumed that only one public key is used to sign. + * Only ed25519 keys and hence signatures are currently supported. + */ message SignaturePair { - bytes pubKeyPrefix = 1; // First few bytes of the public key + /** + * First few bytes of the public key + */ + bytes pubKeyPrefix = 1; + oneof signature { - bytes contract = 2; // smart contract virtual signature (always length zero) - bytes ed25519 = 3; // ed25519 signature - bytes RSA_3072 = 4; //RSA-3072 signature - bytes ECDSA_384 = 5; //ECDSA p-384 signature + /** + * smart contract virtual signature (always length zero) + */ + bytes contract = 2; + + /** + * ed25519 signature + */ + bytes ed25519 = 3; + + /** + * RSA-3072 signature + */ + bytes RSA_3072 = 4; + + /** + * ECDSA p-384 signature + */ + bytes ECDSA_384 = 5; } } -/* -A set of signatures corresponding to every unique public key used to sign a given transaction. If one public key matches more than one prefixes on the signature map, the transaction containing the map will fail immediately with the response code KEY_PREFIX_MISMATCH. -*/ +/** + * A set of signatures corresponding to every unique public key used to sign a given transaction. If + * one public key matches more than one prefixes on the signature map, the transaction containing + * the map will fail immediately with the response code KEY_PREFIX_MISMATCH. + */ message SignatureMap { - repeated SignaturePair sigPair = 1; // Each signature pair corresponds to a unique Key required to sign the transaction. + /** + * Each signature pair corresponds to a unique Key required to sign the transaction. + */ + repeated SignaturePair sigPair = 1; } -/* -The transactions and queries supported by Hedera Hashgraph. -*/ +/** + * The transactions and queries supported by Hedera Hashgraph. + */ enum HederaFunctionality { - NONE = 0; // UNSPECIFIED - Need to keep first value as unspecified because first element is ignored and not parsed (0 is ignored by parser) - CryptoTransfer = 1; // crypto transfer - CryptoUpdate = 2; // crypto update account - CryptoDelete = 3; // crypto delete account - // Add a livehash to a crypto account - CryptoAddLiveHash = 4; - // Delete a livehash from a crypto account - CryptoDeleteLiveHash = 5; - ContractCall = 6; // Smart Contract Call - ContractCreate = 7; // Smart Contract Create Contract - ContractUpdate = 8; // Smart Contract update contract - FileCreate = 9; // File Operation create file - FileAppend = 10; // File Operation append file - FileUpdate = 11; // File Operation update file - FileDelete = 12; // File Operation delete file - CryptoGetAccountBalance = 13; // crypto get account balance - CryptoGetAccountRecords = 14; // crypto get account record - CryptoGetInfo = 15; // Crypto get info - ContractCallLocal = 16; // Smart Contract Call - ContractGetInfo = 17; // Smart Contract get info - ContractGetBytecode = 18; // Smart Contract, get the byte code - GetBySolidityID = 19; // Smart Contract, get by solidity ID - GetByKey = 20; // Smart Contract, get by key - // Get a live hash from a crypto account - CryptoGetLiveHash = 21; - CryptoGetStakers = 22; // Crypto, get the stakers for the node - FileGetContents = 23; // File Operations get file contents - FileGetInfo = 24; // File Operations get the info of the file - TransactionGetRecord = 25; // Crypto get the transaction records - ContractGetRecords = 26; // Contract get the transaction records - CryptoCreate = 27; // crypto create account - SystemDelete = 28; // system delete file - SystemUndelete = 29; // system undelete file - ContractDelete = 30; // delete contract - Freeze = 31; // freeze - CreateTransactionRecord = 32; // Create Tx Record - CryptoAccountAutoRenew = 33; // Crypto Auto Renew - ContractAutoRenew = 34; // Contract Auto Renew - GetVersionInfo = 35; //Get Version - TransactionGetReceipt = 36; // Transaction Get Receipt - ConsensusCreateTopic = 50; // Create Topic - ConsensusUpdateTopic = 51; // Update Topic - ConsensusDeleteTopic = 52; // Delete Topic - ConsensusGetTopicInfo = 53; // Get Topic information - ConsensusSubmitMessage = 54; // Submit message to topic - UncheckedSubmit = 55; - TokenCreate = 56; // Create Token - TokenGetInfo = 58; // Get Token information - TokenFreezeAccount = 59; // Freeze Account - TokenUnfreezeAccount = 60; // Unfreeze Account - TokenGrantKycToAccount = 61; // Grant KYC to Account - TokenRevokeKycFromAccount = 62; // Revoke KYC from Account - TokenDelete = 63; // Delete Token - TokenUpdate = 64; // Update Token - TokenMint = 65; // Mint tokens to treasury - TokenBurn = 66; // Burn tokens from treasury - TokenAccountWipe = 67; // Wipe token amount from Account holder - TokenAssociateToAccount = 68; // Associate tokens to an account - TokenDissociateFromAccount = 69; // Dissociate tokens from an account - ScheduleCreate = 70; // Create Scheduled Transaction - ScheduleDelete = 71; // Delete Scheduled Transaction - ScheduleSign = 72; // Sign Scheduled Transaction - ScheduleGetInfo = 73; // Get Scheduled Transaction Information - TokenGetAccountNftInfos = 74; // Get Token Account Nft Information - TokenGetNftInfo = 75; // Get Token Nft Information - TokenGetNftInfos = 76; // Get Token Nft List Information - TokenFeeScheduleUpdate = 77; // Update a token's custom fee schedule, if permissible -} - -/* -A set of prices the nodes use in determining transaction and query fees, and constants involved in fee calculations. -Nodes multiply the amount of resources consumed by a transaction or query by the corresponding price to calculate the -appropriate fee. Units are one-thousandth of a tinyCent.*/ -message FeeComponents { - int64 min = 1; // A minimum, the calculated fee must be greater than this value - int64 max = 2; // A maximum, the calculated fee must be less than this value - int64 constant = 3; // A constant contribution to the fee - int64 bpt = 4; // The price of bandwidth consumed by a transaction, measured in bytes - int64 vpt = 5; // The price per signature verification for a transaction - int64 rbh = 6; // The price of RAM consumed by a transaction, measured in byte-hours - int64 sbh = 7; // The price of storage consumed by a transaction, measured in byte-hours - int64 gas = 8; // The price of computation for a smart contract transaction, measured in gas - int64 tv = 9; // The price per hbar transferred for a transfer - int64 bpr = 10; // The price of bandwidth for data retrieved from memory for a response, measured in bytes - int64 sbpr = 11; // The price of bandwidth for data retrieved from disk for a response, measured in bytes -} - -/* The fees for a specific transaction or query based on the fee data. */ -message TransactionFeeSchedule { - // A particular transaction or query - HederaFunctionality hederaFunctionality = 1; - // Resource price coefficients - FeeData feeData = 2 [deprecated=true]; - // Resource price coefficients. Supports subtype price definition. - repeated FeeData fees = 3; -} + /** + * UNSPECIFIED - Need to keep first value as unspecified because first element is ignored and + * not parsed (0 is ignored by parser) + */ + NONE = 0; -/* -The total fee charged for a transaction. It is composed of three components – a node fee that compensates the specific node that submitted the transaction, a network fee that compensates the network for assigning the transaction a consensus timestamp, and a service fee that compensates the network for the ongoing maintenance of the consequences of the transaction. -*/ -message FeeData { - // Fee paid to the submitting node - FeeComponents nodedata = 1; - // Fee paid to the network for processing a transaction into consensus - FeeComponents networkdata = 2; - // Fee paid to the network for providing the service associated with the transaction; for instance, storing a file - FeeComponents servicedata = 3; - // SubType distinguishing between different types of FeeData, correlating to the same HederaFunctionality - SubType subType = 4; -} + /** + * crypto transfer + */ + CryptoTransfer = 1; -/* -A list of resource prices fee for different transactions and queries and the time period at which this fee schedule will expire. Nodes use the prices to determine the fees for all transactions based on how much of those resources each transaction uses. -*/ -message FeeSchedule { - // List of price coefficients for network resources - repeated TransactionFeeSchedule transactionFeeSchedule = 1; - // FeeSchedule expiry time - TimestampSeconds expiryTime = 2; -} + /** + * crypto update account + */ + CryptoUpdate = 2; -/* This contains two Fee Schedules with expiry timestamp. */ -message CurrentAndNextFeeSchedule { - FeeSchedule currentFeeSchedule = 1; // Contains current Fee Schedule - FeeSchedule nextFeeSchedule = 2; // Contains next Fee Schedule -} + /** + * crypto delete account + */ + CryptoDelete = 3; -/* -Contains the IP address and the port representing a service endpoint of a Node in a network. Used to reach the Hedera API and submit transactions to the network. -*/ -message ServiceEndpoint { - bytes ipAddressV4 = 1; // The 32-bit IPv4 address of the node encoded in left to right order (e.g. 127.0.0.1 has 127 as its first byte) - int32 port = 2; // The port of the node -} + /** + * Add a livehash to a crypto account + */ + CryptoAddLiveHash = 4; -/* -The data about a node, including its service endpoints and the Hedera account to be paid for services -provided by the node (that is, queries answered and transactions submitted.) + /** + * Delete a livehash from a crypto account + */ + CryptoDeleteLiveHash = 5; -If the serviceEndpoint list is not set, or empty, then the endpoint given by the (deprecated) -ipAddress and portno fields should be used. + /** + * Smart Contract Call + */ + ContractCall = 6; -All fields are populated in the 0.0.102 address book file while only fields that start with # are populated in the 0.0.101 address book file. -*/ -message NodeAddress { - bytes ipAddress = 1 [deprecated=true]; // The IP address of the Node with separator & octets encoded in UTF-8. Usage is deprecated, ServiceEndpoint is preferred to retrieve a node's list of IP addresses and ports - int32 portno = 2 [deprecated=true]; // The port number of the grpc server for the node. Usage is deprecated, ServiceEndpoint is preferred to retrieve a node's list of IP addresses and ports - bytes memo = 3 [deprecated=true]; // Usage is deprecated, nodeAccountId is preferred to retrieve a node's account ID - string RSA_PubKey = 4; // The node's hex-encoded X509 RSA public key - int64 nodeId = 5; // # A non-sequential identifier for the node - AccountID nodeAccountId = 6; // # The account to be paid for queries and transactions sent to this node - bytes nodeCertHash = 7; // # The hex-encoded SHA-384 hash of the X509 cert used to encrypt gRPC traffic to the node - repeated ServiceEndpoint serviceEndpoint = 8; // # A node's service IP addresses and ports - string description = 9; // A description of the node, with UTF-8 encoding up to 100 bytes - int64 stake = 10; // The amount of tinybars staked to the node -} - -/* -A list of nodes and their metadata that contains all details of the nodes for the network. - -Used to parse the contents of system files 0.0.101 and 0.0.102. -*/ -message NodeAddressBook { - repeated NodeAddress nodeAddress = 1; // Metadata of all nodes in the network -} + /** + * Smart Contract Create Contract + */ + ContractCreate = 7; -/* Hedera follows semantic versioning (https://semver.org/) for both the HAPI protobufs and the Services software. -This type allows the getVersionInfo query in the NetworkService to return the deployed versions -of both protobufs and software on the node answering the query. */ + /** + * Smart Contract update contract + */ + ContractUpdate = 8; + + /** + * File Operation create file + */ + FileCreate = 9; + + /** + * File Operation append file + */ + FileAppend = 10; + + /** + * File Operation update file + */ + FileUpdate = 11; + + /** + * File Operation delete file + */ + FileDelete = 12; + + /** + * crypto get account balance + */ + CryptoGetAccountBalance = 13; + + /** + * crypto get account record + */ + CryptoGetAccountRecords = 14; + + /** + * Crypto get info + */ + CryptoGetInfo = 15; + + /** + * Smart Contract Call + */ + ContractCallLocal = 16; + + /** + * Smart Contract get info + */ + ContractGetInfo = 17; + + /** + * Smart Contract, get the byte code + */ + ContractGetBytecode = 18; + + /** + * Smart Contract, get by solidity ID + */ + GetBySolidityID = 19; + + /** + * Smart Contract, get by key + */ + GetByKey = 20; + + /** + * Get a live hash from a crypto account + */ + CryptoGetLiveHash = 21; + + /** + * Crypto, get the stakers for the node + */ + CryptoGetStakers = 22; + + /** + * File Operations get file contents + */ + FileGetContents = 23; + + /** + * File Operations get the info of the file + */ + FileGetInfo = 24; + + /** + * Crypto get the transaction records + */ + TransactionGetRecord = 25; + + /** + * Contract get the transaction records + */ + ContractGetRecords = 26; + + /** + * crypto create account + */ + CryptoCreate = 27; + + /** + * system delete file + */ + SystemDelete = 28; + + /** + * system undelete file + */ + SystemUndelete = 29; + + /** + * delete contract + */ + ContractDelete = 30; + + /** + * freeze + */ + Freeze = 31; + + /** + * Create Tx Record + */ + CreateTransactionRecord = 32; + + /** + * Crypto Auto Renew + */ + CryptoAccountAutoRenew = 33; + + /** + * Contract Auto Renew + */ + ContractAutoRenew = 34; + + /** + * Get Version + */ + GetVersionInfo = 35; + + /** + * Transaction Get Receipt + */ + TransactionGetReceipt = 36; + + /** + * Create Topic + */ + ConsensusCreateTopic = 50; + + /** + * Update Topic + */ + ConsensusUpdateTopic = 51; + + /** + * Delete Topic + */ + ConsensusDeleteTopic = 52; + + /** + * Get Topic information + */ + ConsensusGetTopicInfo = 53; + + /** + * Submit message to topic + */ + ConsensusSubmitMessage = 54; + + UncheckedSubmit = 55; + /** + * Create Token + */ + TokenCreate = 56; + + /** + * Get Token information + */ + TokenGetInfo = 58; + + /** + * Freeze Account + */ + TokenFreezeAccount = 59; + + /** + * Unfreeze Account + */ + TokenUnfreezeAccount = 60; + + /** + * Grant KYC to Account + */ + TokenGrantKycToAccount = 61; + + /** + * Revoke KYC from Account + */ + TokenRevokeKycFromAccount = 62; + + /** + * Delete Token + */ + TokenDelete = 63; + + /** + * Update Token + */ + TokenUpdate = 64; + + /** + * Mint tokens to treasury + */ + TokenMint = 65; + + /** + * Burn tokens from treasury + */ + TokenBurn = 66; + + /** + * Wipe token amount from Account holder + */ + TokenAccountWipe = 67; + + /** + * Associate tokens to an account + */ + TokenAssociateToAccount = 68; + + /** + * Dissociate tokens from an account + */ + TokenDissociateFromAccount = 69; + + /** + * Create Scheduled Transaction + */ + ScheduleCreate = 70; + + /** + * Delete Scheduled Transaction + */ + ScheduleDelete = 71; + + /** + * Sign Scheduled Transaction + */ + ScheduleSign = 72; + + /** + * Get Scheduled Transaction Information + */ + ScheduleGetInfo = 73; + + /** + * Get Token Account Nft Information + */ + TokenGetAccountNftInfos = 74; + + /** + * Get Token Nft Information + */ + TokenGetNftInfo = 75; + + /** + * Get Token Nft List Information + */ + TokenGetNftInfos = 76; + + /** + * Update a token's custom fee schedule, if permissible + */ + TokenFeeScheduleUpdate = 77; +} + +/** + * A set of prices the nodes use in determining transaction and query fees, and constants involved + * in fee calculations. Nodes multiply the amount of resources consumed by a transaction or query + * by the corresponding price to calculate the appropriate fee. Units are one-thousandth of a + * tinyCent. + */ +message FeeComponents { + /** + * A minimum, the calculated fee must be greater than this value + */ + int64 min = 1; + + /** + * A maximum, the calculated fee must be less than this value + */ + int64 max = 2; + + /** + * A constant contribution to the fee + */ + int64 constant = 3; + + /** + * The price of bandwidth consumed by a transaction, measured in bytes + */ + int64 bpt = 4; + + /** + * The price per signature verification for a transaction + */ + int64 vpt = 5; + + /** + * The price of RAM consumed by a transaction, measured in byte-hours + */ + int64 rbh = 6; + + /** + * The price of storage consumed by a transaction, measured in byte-hours + */ + int64 sbh = 7; + + /** + * The price of computation for a smart contract transaction, measured in gas + */ + int64 gas = 8; + + /** + * The price per hbar transferred for a transfer + */ + int64 tv = 9; + + /** + * The price of bandwidth for data retrieved from memory for a response, measured in bytes + */ + int64 bpr = 10; + + /** + * The price of bandwidth for data retrieved from disk for a response, measured in bytes + */ + int64 sbpr = 11; +} + +/** + * The fees for a specific transaction or query based on the fee data. + */ +message TransactionFeeSchedule { + /** + * A particular transaction or query + */ + HederaFunctionality hederaFunctionality = 1; + + /** + * Resource price coefficients + */ + FeeData feeData = 2 [deprecated=true]; + + /** + * Resource price coefficients. Supports subtype price definition. + */ + repeated FeeData fees = 3; +} + +/** + * The total fee charged for a transaction. It is composed of three components – a node fee that + * compensates the specific node that submitted the transaction, a network fee that compensates the + * network for assigning the transaction a consensus timestamp, and a service fee that compensates + * the network for the ongoing maintenance of the consequences of the transaction. + */ +message FeeData { + /** + * Fee paid to the submitting node + */ + FeeComponents nodedata = 1; + + /** + * Fee paid to the network for processing a transaction into consensus + */ + FeeComponents networkdata = 2; + + /** + * Fee paid to the network for providing the service associated with the + * transaction; for instance, storing a file + */ + FeeComponents servicedata = 3; + + /** + * SubType distinguishing between different types of FeeData, correlating + * to the same HederaFunctionality + */ + SubType subType = 4; +} + +/** + * A list of resource prices fee for different transactions and queries and the time period at which + * this fee schedule will expire. Nodes use the prices to determine the fees for all transactions + * based on how much of those resources each transaction uses. + */ +message FeeSchedule { + /** + * List of price coefficients for network resources + */ + repeated TransactionFeeSchedule transactionFeeSchedule = 1; + + /** + * FeeSchedule expiry time + */ + TimestampSeconds expiryTime = 2; +} + +/** + * This contains two Fee Schedules with expiry timestamp. + */ +message CurrentAndNextFeeSchedule { + /** + * Contains current Fee Schedule + */ + FeeSchedule currentFeeSchedule = 1; + + /** + * Contains next Fee Schedule + */ + FeeSchedule nextFeeSchedule = 2; +} + +/** + * Contains the IP address and the port representing a service endpoint of a Node in a network. Used + * to reach the Hedera API and submit transactions to the network. + */ +message ServiceEndpoint { + /** + * The 32-bit IPv4 address of the node encoded in left to right order (e.g. 127.0.0.1 has 127 + * as its first byte) + */ + bytes ipAddressV4 = 1; + + /** + * The port of the node + */ + int32 port = 2; +} + +/** + * The data about a node, including its service endpoints and the Hedera account to be paid for + * services provided by the node (that is, queries answered and transactions submitted.) + * + * If the serviceEndpoint list is not set, or empty, then the endpoint given by the + * (deprecated) ipAddress and portno fields should be used. + * + * All fields are populated in the 0.0.102 address book file while only fields that start with # are + * populated in the 0.0.101 address book file. + */ +message NodeAddress { + /** + * The IP address of the Node with separator & octets encoded in UTF-8. Usage is deprecated, + * ServiceEndpoint is preferred to retrieve a node's list of IP addresses and ports + */ + bytes ipAddress = 1 [deprecated=true]; + + /** + * The port number of the grpc server for the node. Usage is deprecated, ServiceEndpoint is + * preferred to retrieve a node's list of IP addresses and ports + */ + int32 portno = 2 [deprecated=true]; + + /** + * Usage is deprecated, nodeAccountId is preferred to retrieve a node's account ID + */ + bytes memo = 3 [deprecated=true]; + + /** + * The node's hex-encoded X509 RSA public key + */ + string RSA_PubKey = 4; + + /** + * # A non-sequential identifier for the node + */ + int64 nodeId = 5; + + /** + * # The account to be paid for queries and transactions sent to this node + */ + AccountID nodeAccountId = 6; + + /** + * # The hex-encoded SHA-384 hash of the X509 cert used to encrypt gRPC traffic to the node + */ + bytes nodeCertHash = 7; + + /** + * # A node's service IP addresses and ports + */ + repeated ServiceEndpoint serviceEndpoint = 8; + + /** + * A description of the node, with UTF-8 encoding up to 100 bytes + */ + string description = 9; + + /** + * The amount of tinybars staked to the node + */ + int64 stake = 10; +} + +/** + * A list of nodes and their metadata that contains all details of the nodes for the network. Used + * to parse the contents of system files 0.0.101 and 0.0.102. + */ +message NodeAddressBook { + /** + * Metadata of all nodes in the network + */ + repeated NodeAddress nodeAddress = 1; +} + +/** + * Hedera follows semantic versioning (https://semver.org/) for both the HAPI protobufs and the + * Services software. This type allows the getVersionInfo query in the + * NetworkService to return the deployed versions of both protobufs and software on the + * node answering the query. + */ message SemanticVersion { - int32 major = 1; // Increases with incompatible API changes - int32 minor = 2; // Increases with backwards-compatible new functionality - int32 patch = 3; // Increases with backwards-compatible bug fixes - string pre = 4; // A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers (https://semver.org/#spec-item-9); so given a semver 0.14.0-alpha.1+21AF26D3, this field would contain 'alpha.1' - string build = 5; // Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version (https://semver.org/#spec-item-10); so given a semver 0.14.0-alpha.1+21AF26D3, this field would contain '21AF26D3' + /** + * Increases with incompatible API changes + */ + int32 major = 1; + + /** + * Increases with backwards-compatible new functionality + */ + int32 minor = 2; + + /** + * Increases with backwards-compatible bug fixes + */ + int32 patch = 3; + + /** + * A pre-release version MAY be denoted by appending a hyphen and a series of dot separated + * identifiers (https://semver.org/#spec-item-9); so given a semver 0.14.0-alpha.1+21AF26D3, + * this field would contain 'alpha.1' + */ + string pre = 4; + + /** + * Build metadata MAY be denoted by appending a plus sign and a series of dot separated + * identifiers immediately following the patch or pre-release version + * (https://semver.org/#spec-item-10); so given a semver 0.14.0-alpha.1+21AF26D3, this field + * would contain '21AF26D3' + */ + string build = 5; } +/** + * UNDOCUMENTED + */ message Setting { - string name = 1; // name of the property - string value = 2; // value of the property - bytes data = 3; // any data associated with property + /** + * name of the property + */ + string name = 1; + + /** + * value of the property + */ + string value = 2; + + /** + * any data associated with property + */ + bytes data = 3; } +/** + * UNDOCUMENTED + */ message ServicesConfigurationList { - repeated Setting nameValue = 1; // list of name value pairs of the application properties + /** + * list of name value pairs of the application properties + */ + repeated Setting nameValue = 1; } -/* Token's information related to the given Account */ +/** + * Token's information related to the given Account + */ message TokenRelationship { - TokenID tokenId = 1; // The ID of the token - string symbol = 2; // The Symbol of the token - uint64 balance = 3; // For token of type FUNGIBLE_COMMON - the balance that the Account holds in the smallest denomination. For token of type NON_FUNGIBLE_UNIQUE - the number of NFTs held by the account - TokenKycStatus kycStatus = 4; // The KYC status of the account (KycNotApplicable, Granted or Revoked). If the token does not have KYC key, KycNotApplicable is returned - TokenFreezeStatus freezeStatus = 5; // The Freeze status of the account (FreezeNotApplicable, Frozen or Unfrozen). If the token does not have Freeze key, FreezeNotApplicable is returned - uint32 decimals = 6; // Tokens divide into 10decimals pieces - bool automatic_association = 7; // Specifies if the relationship is created implicitly. False : explicitly associated, True : implicitly associated. -} + /** + * The ID of the token + */ + TokenID tokenId = 1; + + /** + * The Symbol of the token + */ + string symbol = 2; + + /** + * For token of type FUNGIBLE_COMMON - the balance that the Account holds in the smallest + * denomination. For token of type NON_FUNGIBLE_UNIQUE - the number of NFTs held by the account + */ + uint64 balance = 3; + + /** + * The KYC status of the account (KycNotApplicable, Granted or Revoked). If the token does not + * have KYC key, KycNotApplicable is returned + */ + TokenKycStatus kycStatus = 4; + + /** + * The Freeze status of the account (FreezeNotApplicable, Frozen or Unfrozen). If the token does + * not have Freeze key, FreezeNotApplicable is returned + */ + TokenFreezeStatus freezeStatus = 5; -/* A number of transferable units of a certain token. + /** + * Tokens divide into 10decimals pieces + */ + uint32 decimals = 6; -The transferable unit of a token is its smallest denomination, as given by the token's decimals property---each minted token contains 10decimals transferable units. For example, we could think of the cent as the transferable unit of the US dollar (decimals=2); and the tinybar as the transferable unit of hbar (decimals=8). + /** + * Specifies if the relationship is created implicitly. False : explicitly associated, True : + * implicitly associated. + */ + bool automatic_association = 7; +} -Transferable units are not directly comparable across different tokens. */ +/** + * A number of transferable units of a certain token. + * + * The transferable unit of a token is its smallest denomination, as given by the token's + * decimals property---each minted token contains 10decimals + * transferable units. For example, we could think of the cent as the transferable unit of the US + * dollar (decimals=2); and the tinybar as the transferable unit of hbar + * (decimals=8). + * + * Transferable units are not directly comparable across different tokens. + */ message TokenBalance { - TokenID tokenId = 1; // A unique token id - uint64 balance = 2; // Number of transferable units of the identified token. For token of type FUNGIBLE_COMMON - balance in the smallest denomination. For token of type NON_FUNGIBLE_UNIQUE - the number of NFTs held by the account - uint32 decimals = 3; // Tokens divide into 10decimals pieces + /** + * A unique token id + */ + TokenID tokenId = 1; + + /** + * Number of transferable units of the identified token. For token of type FUNGIBLE_COMMON - + * balance in the smallest denomination. For token of type NON_FUNGIBLE_UNIQUE - the number of + * NFTs held by the account + */ + uint64 balance = 2; + + /** + * Tokens divide into 10decimals pieces + */ + uint32 decimals = 3; } -/* A sequence of token balances */ +/** + * A sequence of token balances + */ message TokenBalances { repeated TokenBalance tokenBalances = 1; } @@ -497,4 +1373,4 @@ message TokenBalances { message TokenAssociation { TokenID token_id = 1; // The token involved in the association AccountID account_id = 2; // The account involved in the association -} \ No newline at end of file +} diff --git a/services/consensus_create_topic.proto b/services/consensus_create_topic.proto index 9417eb74..e33861d8 100644 --- a/services/consensus_create_topic.proto +++ b/services/consensus_create_topic.proto @@ -28,32 +28,45 @@ option java_multiple_files = true; import "basic_types.proto"; import "duration.proto"; -// See [ConsensusService.createTopic()](#proto.ConsensusService) +/** + * See [ConsensusService.createTopic()](#proto.ConsensusService) + */ message ConsensusCreateTopicTransactionBody { - string memo = 1; // Short publicly visible memo about the topic. No guarantee of uniqueness. + /** + * Short publicly visible memo about the topic. No guarantee of uniqueness. + */ + string memo = 1; - // Access control for updateTopic/deleteTopic. - // Anyone can increase the topic's expirationTime via ConsensusService.updateTopic(), regardless of the adminKey. - // If no adminKey is specified, updateTopic may only be used to extend the topic's expirationTime, and deleteTopic - // is disallowed. + /** + * Access control for updateTopic/deleteTopic. + * Anyone can increase the topic's expirationTime via ConsensusService.updateTopic(), regardless of the adminKey. + * If no adminKey is specified, updateTopic may only be used to extend the topic's expirationTime, and deleteTopic + * is disallowed. + */ Key adminKey = 2; - // Access control for submitMessage. - // If unspecified, no access control is performed on ConsensusService.submitMessage (all submissions are allowed). + /** + * Access control for submitMessage. + * If unspecified, no access control is performed on ConsensusService.submitMessage (all submissions are allowed). + */ Key submitKey = 3; - // The initial lifetime of the topic and the amount of time to attempt to extend the topic's lifetime by - // automatically at the topic's expirationTime, if the autoRenewAccount is configured (once autoRenew functionality - // is supported by HAPI). - // Limited to MIN_AUTORENEW_PERIOD and MAX_AUTORENEW_PERIOD value by server-side configuration. - // Required. + /** + * The initial lifetime of the topic and the amount of time to attempt to extend the topic's lifetime by + * automatically at the topic's expirationTime, if the autoRenewAccount is configured (once autoRenew functionality + * is supported by HAPI). + * Limited to MIN_AUTORENEW_PERIOD and MAX_AUTORENEW_PERIOD value by server-side configuration. + * Required. + */ Duration autoRenewPeriod = 6; - // Optional account to be used at the topic's expirationTime to extend the life of the topic (once autoRenew - // functionality is supported by HAPI). - // The topic lifetime will be extended up to a maximum of the autoRenewPeriod or however long the topic - // can be extended using all funds on the account (whichever is the smaller duration/amount and if any extension - // is possible with the account's funds). - // If specified, there must be an adminKey and the autoRenewAccount must sign this transaction. + /** + * Optional account to be used at the topic's expirationTime to extend the life of the topic (once autoRenew + * functionality is supported by HAPI). + * The topic lifetime will be extended up to a maximum of the autoRenewPeriod or however long the topic + * can be extended using all funds on the account (whichever is the smaller duration/amount and if any extension + * is possible with the account's funds). + * If specified, there must be an adminKey and the autoRenewAccount must sign this transaction. + */ AccountID autoRenewAccount = 7; } diff --git a/services/consensus_delete_topic.proto b/services/consensus_delete_topic.proto index d3a26920..c20b1ce8 100644 --- a/services/consensus_delete_topic.proto +++ b/services/consensus_delete_topic.proto @@ -27,7 +27,12 @@ option java_multiple_files = true; import "basic_types.proto"; -// See [ConsensusService.deleteTopic()](#proto.ConsensusService) +/** + * See [ConsensusService.deleteTopic()](#proto.ConsensusService) + */ message ConsensusDeleteTopicTransactionBody { - TopicID topicID = 1; // Topic identifier. + /** + * Topic identifier + */ + TopicID topicID = 1; } diff --git a/services/consensus_get_topic_info.proto b/services/consensus_get_topic_info.proto index 0f76d2b3..62a6cdc4 100644 --- a/services/consensus_get_topic_info.proto +++ b/services/consensus_get_topic_info.proto @@ -30,22 +30,39 @@ import "query_header.proto"; import "response_header.proto"; import "consensus_topic_info.proto"; -// See [ConsensusService.getTopicInfo()](#proto.ConsensusService) +/** + * See [ConsensusService.getTopicInfo()](#proto.ConsensusService) + */ message ConsensusGetTopicInfoQuery { - // Standard info sent from client to node, including the signed payment, and what kind of response is requested - // (cost, state proof, both, or neither). + /** + * Standard info sent from client to node, including the signed payment, and what kind of response is requested + * (cost, state proof, both, or neither). + */ QueryHeader header = 1; - // The Topic for which information is being requested + /** + * The Topic for which information is being requested + */ TopicID topicID = 2; } -// Retrieve the parameters of and state of a consensus topic. +/** + * Retrieve the parameters of and state of a consensus topic. + */ message ConsensusGetTopicInfoResponse { - // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither. + /** + * Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither. + */ ResponseHeader header = 1; - TopicID topicID = 2; // Topic identifier. + /** + * Topic identifier. + */ + TopicID topicID = 2; + - ConsensusTopicInfo topicInfo = 5; // Current state of the topic + /** + * Current state of the topic + */ + ConsensusTopicInfo topicInfo = 5; } diff --git a/services/consensus_service.proto b/services/consensus_service.proto index 6f39aafb..22edf5c4 100644 --- a/services/consensus_service.proto +++ b/services/consensus_service.proto @@ -29,47 +29,53 @@ 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. +/** + * 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. + * 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). + * 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 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 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. + * 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. + * 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. + * 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). + * 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). + * 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. + * 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. + /** + * 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. @@ -77,7 +83,8 @@ service ConsensusService { */ rpc createTopic (Transaction) returns (TransactionResponse); - /* Update a topic. + /** + * 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. @@ -86,21 +93,24 @@ service ConsensusService { */ rpc updateTopic (Transaction) returns (TransactionResponse); - /* Delete a topic. No more transactions or queries on the topic (via HAPI) will succeed. + /** + * 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. + /** + * 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. + /** + * 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. diff --git a/services/consensus_submit_message.proto b/services/consensus_submit_message.proto index e1e1335f..bc482b44 100644 --- a/services/consensus_submit_message.proto +++ b/services/consensus_submit_message.proto @@ -27,14 +27,42 @@ option java_multiple_files = true; import "basic_types.proto"; +/** + * UNDOCUMENTED + */ message ConsensusMessageChunkInfo { - TransactionID initialTransactionID = 1; // TransactionID of the first chunk, gets copied to every subsequent chunk in a fragmented message. - int32 total = 2; // The total number of chunks in the message. - int32 number = 3; // The sequence number (from 1 to total) of the current chunk in the message. + /** + * TransactionID of the first chunk, gets copied to every subsequent chunk in a fragmented message. + */ + TransactionID initialTransactionID = 1; + + /** + * The total number of chunks in the message. + */ + int32 total = 2; + + /** + * The sequence number (from 1 to total) of the current chunk in the message. + */ + int32 number = 3; } +/** + * UNDOCUMENTED + */ message ConsensusSubmitMessageTransactionBody { - TopicID topicID = 1; // Topic to submit message to. - bytes message = 2; // Message to be submitted. Max size of the Transaction (including signatures) is 6KiB. - ConsensusMessageChunkInfo chunkInfo = 3; // Optional information of the current chunk in a fragmented message. + /** + * Topic to submit message to. + */ + TopicID topicID = 1; + + /** + * Message to be submitted. Max size of the Transaction (including signatures) is 6KiB. + */ + bytes message = 2; + + /** + * Optional information of the current chunk in a fragmented message. + */ + ConsensusMessageChunkInfo chunkInfo = 3; } diff --git a/services/consensus_topic_info.proto b/services/consensus_topic_info.proto index 7ca195f9..60ad50fa 100644 --- a/services/consensus_topic_info.proto +++ b/services/consensus_topic_info.proto @@ -29,28 +29,56 @@ import "basic_types.proto"; import "duration.proto"; import "timestamp.proto"; -// Current state of a topic. +/** + * Current state of a topic. + */ message ConsensusTopicInfo { - string memo = 1; // The memo associated with the topic (UTF-8 encoding max 100 bytes) - - // When a topic is created, its running hash is initialized to 48 bytes of binary zeros. - // For each submitted message, the topic's running hash is then updated to the output - // of a particular SHA-384 digest whose input data include the previous running hash. - // - // See the TransactionReceipt.proto documentation for an exact description of the - // data included in the SHA-384 digest used for the update. + /** + * The memo associated with the topic (UTF-8 encoding max 100 bytes) + */ + string memo = 1; + + + /** + * When a topic is created, its running hash is initialized to 48 bytes of binary zeros. + * For each submitted message, the topic's running hash is then updated to the output + * of a particular SHA-384 digest whose input data include the previous running hash. + * + * See the TransactionReceipt.proto documentation for an exact description of the + * data included in the SHA-384 digest used for the update. + */ bytes runningHash = 2; - // Sequence number (starting at 1 for the first submitMessage) of messages on the topic. + /** + * Sequence number (starting at 1 for the first submitMessage) of messages on the topic. + */ uint64 sequenceNumber = 3; - // Effective consensus timestamp at (and after) which submitMessage calls will no longer succeed on the topic - // and the topic will expire and after AUTORENEW_GRACE_PERIOD be automatically deleted. + /** + * Effective consensus timestamp at (and after) which submitMessage calls will no longer succeed on the topic + * and the topic will expire and after AUTORENEW_GRACE_PERIOD be automatically deleted. + */ Timestamp expirationTime = 4; - Key adminKey = 5; // Access control for update/delete of the topic. Null if there is no key. - Key submitKey = 6; // Access control for ConsensusService.submitMessage. Null if there is no key. + /** + * Access control for update/delete of the topic. Null if there is no key. + */ + Key adminKey = 5; + + /** + * Access control for ConsensusService.submitMessage. Null if there is no key. + */ + Key submitKey = 6; + + /** + * If an auto-renew account is specified, when the topic expires, its lifetime will be extended + * by up to this duration (depending on the solvency of the auto-renew account). If the + * auto-renew account has no funds at all, the topic will be deleted instead. + */ + Duration autoRenewPeriod = 7; - Duration autoRenewPeriod = 7; // If an auto-renew account is specified, when the topic expires, its lifetime will be extended by up to this duration (depending on the solvency of the auto-renew account). If the auto-renew account has no funds at all, the topic will be deleted instead. - AccountID autoRenewAccount = 8; // The account, if any, to charge for automatic renewal of the topic's lifetime upon expiry. + /** + * The account, if any, to charge for automatic renewal of the topic's lifetime upon expiry. + */ + AccountID autoRenewAccount = 8; } diff --git a/services/consensus_update_topic.proto b/services/consensus_update_topic.proto index f4da3dc3..55c2df9e 100644 --- a/services/consensus_update_topic.proto +++ b/services/consensus_update_topic.proto @@ -30,42 +30,60 @@ import "basic_types.proto"; import "duration.proto"; import "timestamp.proto"; -// All fields left null will not be updated. -// See [ConsensusService.updateTopic()](#proto.ConsensusService) +/** + * All fields left null will not be updated. + * See [ConsensusService.updateTopic()](#proto.ConsensusService) + */ message ConsensusUpdateTopicTransactionBody { + /** + * UNDOCUMENTED + */ TopicID topicID = 1; - google.protobuf.StringValue memo = 2; // If set, the new memo to be associated with the topic (UTF-8 encoding max 100 bytes) + /** + * If set, the new memo to be associated with the topic (UTF-8 encoding max 100 bytes) + */ + google.protobuf.StringValue memo = 2; - // Effective consensus timestamp at (and after) which all consensus transactions and queries will fail. - // The expirationTime may be no longer than MAX_AUTORENEW_PERIOD (8000001 seconds) from the consensus timestamp of - // this transaction. - // On topics with no adminKey, extending the expirationTime is the only updateTopic option allowed on the topic. - // If unspecified, no change. + /** + * Effective consensus timestamp at (and after) which all consensus transactions and queries will fail. + * The expirationTime may be no longer than MAX_AUTORENEW_PERIOD (8000001 seconds) from the consensus timestamp of + * this transaction. + * On topics with no adminKey, extending the expirationTime is the only updateTopic option allowed on the topic. + * If unspecified, no change. + */ Timestamp expirationTime = 4; - // Access control for update/delete of the topic. - // If unspecified, no change. - // If empty keyList - the adminKey is cleared. + /** + * Access control for update/delete of the topic. + * If unspecified, no change. + * If empty keyList - the adminKey is cleared. + */ Key adminKey = 6; - // Access control for ConsensusService.submitMessage. - // If unspecified, no change. - // If empty keyList - the submitKey is cleared. + /** + * Access control for ConsensusService.submitMessage. + * If unspecified, no change. + * If empty keyList - the submitKey is cleared. + */ Key submitKey = 7; - // The amount of time to extend the topic's lifetime automatically at expirationTime if the autoRenewAccount is - // configured and has funds (once autoRenew functionality is supported by HAPI). - // Limited to between MIN_AUTORENEW_PERIOD (6999999 seconds) and MAX_AUTORENEW_PERIOD (8000001 seconds) by - // servers-side configuration (which may change). - // If unspecified, no change. + /* + * The amount of time to extend the topic's lifetime automatically at expirationTime if the autoRenewAccount is + * configured and has funds (once autoRenew functionality is supported by HAPI). + * Limited to between MIN_AUTORENEW_PERIOD (6999999 seconds) and MAX_AUTORENEW_PERIOD (8000001 seconds) by + * servers-side configuration (which may change). + * If unspecified, no change. + */ Duration autoRenewPeriod = 8; - // Optional account to be used at the topic's expirationTime to extend the life of the topic. - // Once autoRenew functionality is supported by HAPI, the topic lifetime will be extended up to a maximum of the - // autoRenewPeriod or however long the topic can be extended using all funds on the account (whichever is the - // smaller duration/amount). - // If specified as the default value (0.0.0), the autoRenewAccount will be removed. - // If unspecified, no change. + /** + * Optional account to be used at the topic's expirationTime to extend the life of the topic. + * Once autoRenew functionality is supported by HAPI, the topic lifetime will be extended up to a maximum of the + * autoRenewPeriod or however long the topic can be extended using all funds on the account (whichever is the + * smaller duration/amount). + * If specified as the default value (0.0.0), the autoRenewAccount will be removed. + * If unspecified, no change. + */ AccountID autoRenewAccount = 9; } diff --git a/services/contract_call.proto b/services/contract_call.proto index dfedc3dd..3d1124dd 100644 --- a/services/contract_call.proto +++ b/services/contract_call.proto @@ -26,19 +26,37 @@ option java_package = "com.hederahashgraph.api.proto.java"; option java_multiple_files = true; import "basic_types.proto"; -/* -Call a function of the given smart contract instance, giving it functionParameters as its inputs. -The call can use at maximum the given amount of gas – the paying account will not be charged for any unspent gas. -If this function results in data being stored, an amount of gas is calculated that reflects this storage burden. +/** + * Call a function of the given smart contract instance, giving it functionParameters as its inputs. + * The call can use at maximum the given amount of gas – the paying account will not be charged for + * any unspent gas. + * + * If this function results in data being stored, an amount of gas is calculated that reflects this + * storage burden. + * + * The amount of gas used, as well as other attributes of the transaction, e.g. size, number of + * signatures to be verified, determine the fee for the transaction – which is charged to the paying + * account. + */ +message ContractCallTransactionBody { + /** + * the contract instance to call, in the format used in transactions + */ + ContractID contractID = 1; -The amount of gas used, as well as other attributes of the transaction, e.g. size, number of signatures to be verified, -determine the fee for the transaction – which is charged to the paying account. -*/ + /** + * the maximum amount of gas to use for the call + */ + int64 gas = 2; -message ContractCallTransactionBody { - ContractID contractID = 1; // the contract instance to call, in the format used in transactions - int64 gas = 2; // the maximum amount of gas to use for the call - int64 amount = 3; // number of tinybars sent (the function must be payable if this is nonzero) - bytes functionParameters = 4; // which function to call, and the parameters to pass to the function + /** + * number of tinybars sent (the function must be payable if this is nonzero) + */ + int64 amount = 3; + + /** + * which function to call, and the parameters to pass to the function + */ + bytes functionParameters = 4; } diff --git a/services/contract_call_local.proto b/services/contract_call_local.proto index 3d563039..bedce5f0 100644 --- a/services/contract_call_local.proto +++ b/services/contract_call_local.proto @@ -29,46 +29,124 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* The log information for an event returned by a smart contract function call. One function call may return several such events. */ +/** + * The log information for an event returned by a smart contract function call. One function call + * may return several such events. + */ message ContractLoginfo { - ContractID contractID = 1; // address of a contract that emitted the event - bytes bloom = 2; // bloom filter for a particular log - repeated bytes topic = 3; // topics of a particular event - bytes data = 4; // event data + /** + * address of a contract that emitted the event + */ + ContractID contractID = 1; + + /** + * bloom filter for a particular log + */ + bytes bloom = 2; + + /** + * topics of a particular event + */ + repeated bytes topic = 3; + + /** + * event data + */ + bytes data = 4; } -/* The result returned by a call to a smart contract function. This is part of the response to a ContractCallLocal query, and is in the record for a ContractCall or ContractCreateInstance transaction. The ContractCreateInstance transaction record has the results of the call to the constructor. */ +/** + * The result returned by a call to a smart contract function. This is part of the response to a + * ContractCallLocal query, and is in the record for a ContractCall or ContractCreateInstance + * transaction. The ContractCreateInstance transaction record has the results of the call to the + * constructor. + */ message ContractFunctionResult { - ContractID contractID = 1; // the smart contract instance whose function was called - bytes contractCallResult = 2; // the result returned by the function - string errorMessage = 3; // message In case there was an error during smart contract execution - bytes bloom = 4; // bloom filter for record - uint64 gasUsed = 5; // units of gas used to execute contract - repeated ContractLoginfo logInfo = 6; // the log info for events returned by the function - repeated ContractID createdContractIDs = 7; // the list of smart contracts that were created by the function call + /** + * the smart contract instance whose function was called + */ + ContractID contractID = 1; + + /** + * the result returned by the function + */ + bytes contractCallResult = 2; + + /** + * message In case there was an error during smart contract execution + */ + string errorMessage = 3; + + /** + * bloom filter for record + */ + bytes bloom = 4; + + /** + * units of gas used to execute contract + */ + uint64 gasUsed = 5; + + /** + * the log info for events returned by the function + */ + repeated ContractLoginfo logInfo = 6; + + /** + * the list of smart contracts that were created by the function call + */ + repeated ContractID createdContractIDs = 7; } -/* -Call a function of the given smart contract instance, giving it functionParameters as its inputs. -This is performed locally on the particular node that the client is communicating with. -It cannot change the state of the contract instance (and so, cannot spend anything from the instance's cryptocurrency account). -It will not have a consensus timestamp. It cannot generate a record or a receipt. The response will contain the output -returned by the function call. This is useful for calling getter functions, which purely read the state and don't change it. -It is faster and cheaper than a normal call, because it is purely local to a single node. - -Unlike a ContractCall transaction, the node will consume the entire amount of provided gas in determining -the fee for this query. -*/ +/** + * Call a function of the given smart contract instance, giving it functionParameters as its inputs. + * This is performed locally on the particular node that the client is communicating with. + * It cannot change the state of the contract instance (and so, cannot spend anything from the instance's cryptocurrency account). + * It will not have a consensus timestamp. It cannot generate a record or a receipt. The response will contain the output + * returned by the function call. This is useful for calling getter functions, which purely read the state and don't change it. + * It is faster and cheaper than a normal call, because it is purely local to a single node. + * + * Unlike a ContractCall transaction, the node will consume the entire amount of provided gas in determining + * the fee for this query. + */ message ContractCallLocalQuery { - QueryHeader header = 1; // standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). The payment must cover the fees and all of the gas offered. - ContractID contractID = 2; // the contract instance to call, in the format used in transactions - int64 gas = 3; // The amount of gas to use for the call; all of the gas offered will be used and charged a corresponding fee - bytes functionParameters = 4; // which function to call, and the parameters to pass to the function - int64 maxResultSize = 5; // max number of bytes that the result might include. The run will fail if it would have returned more than this number of bytes. + /** + * standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). The payment must cover the fees and all of the gas offered. + */ + QueryHeader header = 1; + + /** + * the contract instance to call, in the format used in transactions + */ + ContractID contractID = 2; + + /** + * The amount of gas to use for the call; all of the gas offered will be used and charged a corresponding fee + */ + int64 gas = 3; + + /** + * which function to call, and the parameters to pass to the function + */ + bytes functionParameters = 4; + + /** + * max number of bytes that the result might include. The run will fail if it would have returned more than this number of bytes. + */ + int64 maxResultSize = 5; } -/* Response when the client sends the node ContractCallLocalQuery */ +/** + * Response when the client sends the node ContractCallLocalQuery + */ message ContractCallLocalResponse { - ResponseHeader header = 1; //standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - ContractFunctionResult functionResult = 2; // the value returned by the function (if it completed and didn't fail) + /** + * standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + */ + ResponseHeader header = 1; + + /** + * the value returned by the function (if it completed and didn't fail) + */ + ContractFunctionResult functionResult = 2; } diff --git a/services/contract_create.proto b/services/contract_create.proto index 1bab7d1f..d1af34f5 100644 --- a/services/contract_create.proto +++ b/services/contract_create.proto @@ -24,38 +24,127 @@ package proto; option java_package = "com.hederahashgraph.api.proto.java"; option java_multiple_files = true; + import "basic_types.proto"; import "duration.proto"; -/* -Start a new smart contract instance. After the instance is created, the ContractID for it is in the receipt, and can be -retrieved by the Record or with a GetByKey query. The instance will run the bytecode stored in a previously created -file, referenced either by FileID or by the transaction ID of the transaction that created the file - -The constructor will be executed using the given amount of gas, and any unspent gas will be refunded to the paying account. Constructor inputs come from the given constructorParameters. +/** + * Start a new smart contract instance. After the instance is created, the ContractID for it is in + * the receipt, and can be retrieved by the Record or with a GetByKey query. The instance will run + * the bytecode stored in a previously created file, referenced either by FileID or by the + * transaction ID of the transaction that created the file + * + * + * The constructor will be executed using the given amount of gas, and any unspent gas will be + * refunded to the paying account. Constructor inputs come from the given constructorParameters. + * - The instance will exist for autoRenewPeriod seconds. When that is reached, it will renew + * itself for another autoRenewPeriod seconds by charging its associated cryptocurrency account + * (which it creates here). If it has insufficient cryptocurrency to extend that long, it will + * extend as long as it can. If its balance is zero, the instance will be deleted. * - * The instance will exist for autoRenewPeriod seconds. When that is reached, it will renew itself for another autoRenewPeriod seconds by charging its associated cryptocurrency account (which it creates here). If it has insufficient cryptocurrency to extend that long, it will extend as long as it can. If its balance is zero, the instance will be deleted. + * - A smart contract instance normally enforces rules, so "the code is law". For example, an + * ERC-20 contract prevents a transfer from being undone without a signature by the recipient of + * the transfer. This is always enforced if the contract instance was created with the adminKeys + * being null. But for some uses, it might be desirable to create something like an ERC-20 + * contract that has a specific group of trusted individuals who can act as a "supreme court" + * with the ability to override the normal operation, when a sufficient number of them agree to + * do so. If adminKeys is not null, then they can sign a transaction that can change the state of + * the smart contract in arbitrary ways, such as to reverse a transaction that violates some + * standard of behavior that is not covered by the code itself. The admin keys can also be used + * to change the autoRenewPeriod, and change the adminKeys field itself. The API currently does + * not implement this ability. But it does allow the adminKeys field to be set and queried, and + * will in the future implement such admin abilities for any instance that has a non-null + * adminKeys. * - * A smart contract instance normally enforces rules, so "the code is law". For example, an ERC-20 contract prevents a transfer from being undone without a signature by the recipient of the transfer. This is always enforced if the contract instance was created with the adminKeys being null. But for some uses, it might be desirable to create something like an ERC-20 contract that has a specific group of trusted individuals who can act as a "supreme court" with the ability to override the normal operation, when a sufficient number of them agree to do so. If adminKeys is not null, then they can sign a transaction that can change the state of the smart contract in arbitrary ways, such as to reverse a transaction that violates some standard of behavior that is not covered by the code itself. The admin keys can also be used to change the autoRenewPeriod, and change the adminKeys field itself. The API currently does not implement this ability. But it does allow the adminKeys field to be set and queried, and will in the future implement such admin abilities for any instance that has a non-null adminKeys. + * - If this constructor stores information, it is charged gas to store it. There is a fee in hbars + * to maintain that storage until the expiration time, and that fee is added as part of the + * transaction fee. * - * If this constructor stores information, it is charged gas to store it. There is a fee in hbars to maintain that storage until the expiration time, and that fee is added as part of the transaction fee. + * - An entity (account, file, or smart contract instance) must be created in a particular realm. + * If the realmID is left null, then a new realm will be created with the given admin key. If a + * new realm has a null adminKey, then anyone can create/modify/delete entities in that realm. + * But if an admin key is given, then any transaction to create/modify/delete an entity in that + * realm must be signed by that key, though anyone can still call functions on smart contract + * instances that exist in that realm. A realm ceases to exist when everything within it has + * expired and no longer exists. * - * An entity (account, file, or smart contract instance) must be created in a particular realm. If the realmID is left null, then a new realm will be created with the given admin key. If a new realm has a null adminKey, then anyone can create/modify/delete entities in that realm. But if an admin key is given, then any transaction to create/modify/delete an entity in that realm must be signed by that key, though anyone can still call functions on smart contract instances that exist in that realm. A realm ceases to exist when everything within it has expired and no longer exists. + * - The current API ignores shardID, realmID, and newRealmAdminKey, and creates everything in + * shard 0 and realm 0, with a null key. Future versions of the API will support multiple realms + * and multiple shards. * - * The current API ignores shardID, realmID, and newRealmAdminKey, and creates everything in shard 0 and realm 0, with a null key. Future versions of the API will support multiple realms and multiple shards. - * - * The optional memo field can contain a string whose length is up to 100 bytes. That is the size after Unicode NFD then UTF-8 conversion. This field can be used to describe the smart contract. It could also be used for other purposes. One recommended purpose is to hold a hexadecimal string that is the SHA-384 hash of a PDF file containing a human-readable legal contract. Then, if the admin keys are the public keys of human arbitrators, they can use that legal document to guide their decisions during a binding arbitration tribunal, convened to consider any changes to the smart contract in the future. The memo field can only be changed using the admin keys. If there are no admin keys, then it cannot be changed after the smart contract is created. + * - The optional memo field can contain a string whose length is up to 100 bytes. That is the size + * after Unicode NFD then UTF-8 conversion. This field can be used to describe the smart contract. + * It could also be used for other purposes. One recommended purpose is to hold a hexadecimal + * string that is the SHA-384 hash of a PDF file containing a human-readable legal contract. Then, + * if the admin keys are the public keys of human arbitrators, they can use that legal document to + * guide their decisions during a binding arbitration tribunal, convened to consider any changes + * to the smart contract in the future. The memo field can only be changed using the admin keys. + * If there are no admin keys, then it cannot be changed after the smart contract is created. */ message ContractCreateTransactionBody { - FileID fileID = 1; // the file containing the smart contract byte code. A copy will be made and held by the contract instance, and have the same expiration time as the instance. The file is referenced one of two ways: - Key adminKey = 3; // the state of the instance and its fields can be modified arbitrarily if this key signs a transaction to modify it. If this is null, then such modifications are not possible, and there is no administrator that can override the normal operation of this smart contract instance. Note that if it is created with no admin keys, then there is no administrator to authorize changing the admin keys, so there can never be any admin keys for that instance. - int64 gas = 4; // gas to run the constructor - int64 initialBalance = 5; // initial number of tinybars to put into the cryptocurrency account associated with and owned by the smart contract - AccountID proxyAccountID = 6; // ID of the account to which this account is proxy staked. If proxyAccountID is null, or is an invalid account, or is an account that isn't a node, then this account is automatically proxy staked to a node chosen by the network, but without earning payments. If the proxyAccountID account refuses to accept proxy staking , or if it is not currently running a node, then it will behave as if proxyAccountID was null. - Duration autoRenewPeriod = 8; // the instance will charge its account every this many seconds to renew for this long - bytes constructorParameters = 9; // parameters to pass to the constructor - ShardID shardID = 10; // shard in which to create this - RealmID realmID = 11; // realm in which to create this (leave this null to create a new realm) - Key newRealmAdminKey = 12; // if realmID is null, then this the admin key for the new realm that will be created - string memo = 13; // the memo that was submitted as part of the contract (max 100 bytes) + /** + * the file containing the smart contract byte code. A copy will be made and held by the + * contract instance, and have the same expiration time as the instance. The file is referenced + * one of two ways: + */ + FileID fileID = 1; + + /** + * the state of the instance and its fields can be modified arbitrarily if this key signs a + * transaction to modify it. If this is null, then such modifications are not possible, and + * there is no administrator that can override the normal operation of this smart contract + * instance. Note that if it is created with no admin keys, then there is no administrator to + * authorize changing the admin keys, so there can never be any admin keys for that instance. + */ + Key adminKey = 3; + + /** + * gas to run the constructor + */ + int64 gas = 4; + + /** + * initial number of tinybars to put into the cryptocurrency account associated with and owned + * by the smart contract + */ + int64 initialBalance = 5; + + /** + * ID of the account to which this account is proxy staked. If proxyAccountID is null, or is an + * invalid account, or is an account that isn't a node, then this account is automatically proxy + * staked to a node chosen by the network, but without earning payments. If the proxyAccountID + * account refuses to accept proxy staking , or if it is not currently running a node, then it + * will behave as if proxyAccountID was null. + */ + AccountID proxyAccountID = 6; + + /** + * the instance will charge its account every this many seconds to renew for this long + */ + Duration autoRenewPeriod = 8; + + /** + * parameters to pass to the constructor + */ + bytes constructorParameters = 9; + + /** + * shard in which to create this + */ + ShardID shardID = 10; + + /** + * realm in which to create this (leave this null to create a new realm) + */ + RealmID realmID = 11; + + /** + * if realmID is null, then this the admin key for the new realm that will be created + */ + Key newRealmAdminKey = 12; + + /** + * the memo that was submitted as part of the contract (max 100 bytes) + */ + string memo = 13; } diff --git a/services/contract_delete.proto b/services/contract_delete.proto index c9701189..03392ca7 100644 --- a/services/contract_delete.proto +++ b/services/contract_delete.proto @@ -26,21 +26,32 @@ option java_multiple_files = true; import "basic_types.proto"; -/* -At consensus, marks a contract as deleted and transfers its remaining hBars, if any, to a designated receiver. After a contract is deleted, it can no longer be called. - -If the target contract is immutable (that is, was created without an admin key), then this transaction resolves to MODIFYING_IMMUTABLE_CONTRACT. - ---- Signing Requirements --- -1. The admin key of the target contract must sign. -2. If the transfer account or contract has receiverSigRequired, its associated key must also sign. */ +/** + * At consensus, marks a contract as deleted and transfers its remaining hBars, if any, to a + * designated receiver. After a contract is deleted, it can no longer be called. + * + * If the target contract is immutable (that is, was created without an admin key), then this + * transaction resolves to MODIFYING_IMMUTABLE_CONTRACT. + * + * --- Signing Requirements --- + * 1. The admin key of the target contract must sign. + * 2. If the transfer account or contract has receiverSigRequired, its associated key must also sign + */ message ContractDeleteTransactionBody { - // The id of the contract to be deleted + /** + * The id of the contract to be deleted + */ ContractID contractID = 1; + oneof obtainers { - // The id of an account to receive any remaining hBars from the deleted contract + /** + * The id of an account to receive any remaining hBars from the deleted contract + */ AccountID transferAccountID = 2; - // The id of a contract to receive any remaining hBars from the deleted contract + + /** + * The id of a contract to receive any remaining hBars from the deleted contract + */ ContractID transferContractID = 3; } } diff --git a/services/contract_get_bytecode.proto b/services/contract_get_bytecode.proto index 46359fa9..469d2639 100644 --- a/services/contract_get_bytecode.proto +++ b/services/contract_get_bytecode.proto @@ -29,15 +29,35 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* Get the bytecode for a smart contract instance */ +/** + * Get the bytecode for a smart contract instance + */ message ContractGetBytecodeQuery { - QueryHeader header = 1; // standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - ContractID contractID = 2; // the contract for which information is requested + /** + * standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * the contract for which information is requested + */ + ContractID contractID = 2; } -/* Response when the client sends the node ContractGetBytecodeQuery */ +/** + * Response when the client sends the node ContractGetBytecodeQuery + */ message ContractGetBytecodeResponse { - ResponseHeader header = 1; //standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - bytes bytecode = 6; // the bytecode + /** + * standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + + /** + * the bytecode + */ + bytes bytecode = 6; } diff --git a/services/contract_get_info.proto b/services/contract_get_info.proto index 0af22643..7ddcccec 100644 --- a/services/contract_get_info.proto +++ b/services/contract_get_info.proto @@ -31,28 +31,103 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* Get information about a smart contract instance. This includes the account that it uses, the file containing its bytecode, and the time when it will expire. */ +/** + * Get information about a smart contract instance. This includes the account that it uses, the file + * containing its bytecode, and the time when it will expire. + */ message ContractGetInfoQuery { - QueryHeader header = 1; // standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - ContractID contractID = 2; // the contract for which information is requested + /** + * standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * the contract for which information is requested + */ + ContractID contractID = 2; } -/* Response when the client sends the node ContractGetInfoQuery */ +/** + * Response when the client sends the node ContractGetInfoQuery + */ message ContractGetInfoResponse { - ResponseHeader header = 1; //standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + /** + * standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + message ContractInfo { - ContractID contractID = 1; // ID of the contract instance, in the format used in transactions - AccountID accountID = 2; // ID of the cryptocurrency account owned by the contract instance, in the format used in transactions - string contractAccountID = 3; // ID of both the contract instance and the cryptocurrency account owned by the contract instance, in the format used by Solidity - Key adminKey = 4; // the state of the instance and its fields can be modified arbitrarily if this key signs a transaction to modify it. If this is null, then such modifications are not possible, and there is no administrator that can override the normal operation of this smart contract instance. Note that if it is created with no admin keys, then there is no administrator to authorize changing the admin keys, so there can never be any admin keys for that instance. */ - Timestamp expirationTime = 5; // the current time at which this contract instance (and its account) is set to expire - Duration autoRenewPeriod = 6; // the expiration time will extend every this many seconds. If there are insufficient funds, then it extends as long as possible. If the account is empty when it expires, then it is deleted. - int64 storage = 7; // number of bytes of storage being used by this instance (which affects the cost to extend the expiration time) - string memo = 8; // the memo associated with the contract (max 100 bytes) - uint64 balance = 9; // The current balance, in tinybars - bool deleted = 10; // Whether the contract has been deleted - repeated TokenRelationship tokenRelationships = 11; // The tokens associated to the contract + /** + * ID of the contract instance, in the format used in transactions + */ + ContractID contractID = 1; + + /** + * ID of the cryptocurrency account owned by the contract instance, in the format used in + * transactions + */ + AccountID accountID = 2; + + /** + * ID of both the contract instance and the cryptocurrency account owned by the contract + * instance, in the format used by Solidity + */ + string contractAccountID = 3; + + /** + * the state of the instance and its fields can be modified arbitrarily if this key signs a + * transaction to modify it. If this is null, then such modifications are not possible, and + * there is no administrator that can override the normal operation of this smart contract + * instance. Note that if it is created with no admin keys, then there is no administrator + * to authorize changing the admin keys, so there can never be any admin keys for that + * instance. + */ + Key adminKey = 4; + + /** + * the current time at which this contract instance (and its account) is set to expire + */ + Timestamp expirationTime = 5; + + /** + * the expiration time will extend every this many seconds. If there are insufficient funds, + * then it extends as long as possible. If the account is empty when it expires, then it is + * deleted. + */ + Duration autoRenewPeriod = 6; + + /** + * number of bytes of storage being used by this instance (which affects the cost to extend + * the expiration time) + */ + int64 storage = 7; + + /** + * the memo associated with the contract (max 100 bytes) + */ + string memo = 8; + + /** + * The current balance, in tinybars + */ + uint64 balance = 9; + + /** + * Whether the contract has been deleted + */ + bool deleted = 10; + + /** + * The tokens associated to the contract + */ + repeated TokenRelationship tokenRelationships = 11; } - ContractInfo contractInfo = 2; // the information about this contract instance (a state proof can be generated for this) + + /** + * the information about this contract instance (a state proof can be generated for this) + */ + ContractInfo contractInfo = 2; } diff --git a/services/contract_get_records.proto b/services/contract_get_records.proto index 92a8aaff..a87e2505 100644 --- a/services/contract_get_records.proto +++ b/services/contract_get_records.proto @@ -30,17 +30,39 @@ import "transaction_record.proto"; import "query_header.proto"; import "response_header.proto"; -// Before v0.9.0, requested records of all transactions against the given contract in the last 25 hours. +/** + * Before v0.9.0, requested records of all transactions against the given contract in the last 25 hours. + */ message ContractGetRecordsQuery { option deprecated = true; - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - ContractID contractID = 2; // The smart contract instance for which the records should be retrieved + /** + * Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The smart contract instance for which the records should be retrieved + */ + ContractID contractID = 2; } -// Before v0.9.0, returned records of all transactions against the given contract in the last 25 hours. +/** + * Before v0.9.0, returned records of all transactions against the given contract in the last 25 hours. + */ message ContractGetRecordsResponse { option deprecated = true; - ResponseHeader header = 1; //Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - ContractID contractID = 2; // The smart contract instance that this record is for - repeated TransactionRecord records = 3; // List of records, each with contractCreateResult or contractCallResult as its body + /** + * Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + */ + ResponseHeader header = 1; + + /** + * The smart contract instance that this record is for + */ + ContractID contractID = 2; + + /** + * List of records, each with contractCreateResult or contractCallResult as its body + */ + repeated TransactionRecord records = 3; } diff --git a/services/contract_update.proto b/services/contract_update.proto index 0080899c..914c24ea 100644 --- a/services/contract_update.proto +++ b/services/contract_update.proto @@ -30,32 +30,71 @@ import "duration.proto"; import "timestamp.proto"; import "google/protobuf/wrappers.proto"; -/* -At consensus, updates the fields of a smart contract to the given values. - -If no value is given for a field, that field is left unchanged on the contract. For an immutable smart contract (that is, a contract created without an adminKey), only the expirationTime may be updated; setting any other field in this case will cause the transaction status to resolve to MODIFYING_IMMUTABLE_CONTRACT. - ---- Signing Requirements --- -1. Whether or not a contract has an admin Key, its expiry can be extended with only the transaction payer's signature. -2. Updating any other field of a mutable contract requires the admin key's signature. -3. If the update transaction includes a new admin key, this new key must also sign unless it is exactly an empty KeyList. This special sentinel key removes the existing admin key and causes the contract to become immutable. (Other Key structures without a constituent Ed25519 key will be rejected with INVALID_ADMIN_KEY.) */ +/** + * At consensus, updates the fields of a smart contract to the given values. + * + * If no value is given for a field, that field is left unchanged on the contract. For an immutable + * smart contract (that is, a contract created without an adminKey), only the expirationTime may be + * updated; setting any other field in this case will cause the transaction status to resolve to + * MODIFYING_IMMUTABLE_CONTRACT. + * + * --- Signing Requirements --- + * 1. Whether or not a contract has an admin Key, its expiry can be extended with only the + * transaction payer's signature. + * 2. Updating any other field of a mutable contract requires the admin key's signature. + * 3. If the update transaction includes a new admin key, this new key must also sign unless + * it is exactly an empty KeyList. This special sentinel key removes the existing admin + * key and causes the contract to become immutable. (Other Key structures without a + * constituent Ed25519 key will be rejected with INVALID_ADMIN_KEY.) + */ message ContractUpdateTransactionBody { - // The id of the contract to be updated + /** + * The id of the contract to be updated + */ ContractID contractID = 1; - // The new expiry of the contract, no earlier than the current expiry (resolves to EXPIRATION_REDUCTION_NOT_ALLOWED otherwise) + + /** + * The new expiry of the contract, no earlier than the current expiry (resolves to + * EXPIRATION_REDUCTION_NOT_ALLOWED otherwise) + */ Timestamp expirationTime = 2; - // The new key to control updates to the contract + + /** + * The new key to control updates to the contract + */ Key adminKey = 3; - // (NOT YET IMPLEMENTED) The new id of the account to which the contract is proxy staked + + /** + * (NOT YET IMPLEMENTED) The new id of the account to which the contract is proxy staked + */ AccountID proxyAccountID = 6; - // (NOT YET IMPLEMENTED) The new interval at which the contract will pay to extend its expiry (by the same interval) + + /** + * (NOT YET IMPLEMENTED) The new interval at which the contract will pay to extend its expiry + * (by the same interval) + */ Duration autoRenewPeriod = 7; - // The new id of the file asserted to contain the bytecode of the Solidity transaction that created this contract + + /** + * The new id of the file asserted to contain the bytecode of the Solidity transaction that + * created this contract + */ FileID fileID = 8; - // The new contract memo, assumed to be Unicode encoded with UTF-8 (at most 100 bytes) + + /** + * The new contract memo, assumed to be Unicode encoded with UTF-8 (at most 100 bytes) + */ oneof memoField { - string memo = 9 [deprecated = true]; // [Deprecated] If set with a non-zero length, the new memo to be associated with the account (UTF-8 encoding max 100 bytes) - google.protobuf.StringValue memoWrapper = 10; // If set, the new memo to be associated with the account (UTF-8 encoding max 100 bytes) + /** + * [Deprecated] If set with a non-zero length, the new memo to be associated with the account + * (UTF-8 encoding max 100 bytes) + */ + string memo = 9 [deprecated = true]; + + /** + * If set, the new memo to be associated with the account (UTF-8 encoding max 100 bytes) + */ + google.protobuf.StringValue memoWrapper = 10; } } diff --git a/services/crypto_add_live_hash.proto b/services/crypto_add_live_hash.proto index 573187a8..17620ce9 100644 --- a/services/crypto_add_live_hash.proto +++ b/services/crypto_add_live_hash.proto @@ -29,27 +29,46 @@ option java_multiple_files = true; import "basic_types.proto"; import "duration.proto"; -/* A hash---presumably of some kind of credential or certificate---along with a list of keys, each of which may be either a primitive or a threshold key. */ +/** + * A hash---presumably of some kind of credential or certificate---along with a list of keys, each + * of which may be either a primitive or a threshold key. + */ message LiveHash { - // The account to which the livehash is attached + /** + * The account to which the livehash is attached + */ AccountID accountId = 1; - // The SHA-384 hash of a credential or certificate + + /** + * The SHA-384 hash of a credential or certificate + */ bytes hash = 2; - // A list of keys (primitive or threshold), all of which must sign to attach the livehash to an account, and any one of which can later delete it. + + /** + * A list of keys (primitive or threshold), all of which must sign to attach the livehash to an account, and any one of which can later delete it. + */ KeyList keys = 3; - // The duration for which the livehash will remain valid + + /** + * The duration for which the livehash will remain valid + */ Duration duration = 5; } -/* At consensus, attaches the given livehash to the given account. -The hash can be deleted by the key controlling the account, or by any of the keys associated to the livehash. -Hence livehashes provide a revocation service for their implied credentials; for example, -when an authority grants a credential to the account, the account owner will cosign with the authority (or authorities) -to attach a hash of the credential to the account---hence proving the grant. If the credential is revoked, then any of -the authorities may delete it (or the account owner). In this way, the livehash mechanism acts as a revocation service. -An account cannot have two identical livehashes associated. To modify the list of keys in a livehash, the -livehash should first be deleted, then recreated with a new list of keys. */ +/** + * At consensus, attaches the given livehash to the given account. The hash can be deleted by the + * key controlling the account, or by any of the keys associated to the livehash. Hence livehashes + * provide a revocation service for their implied credentials; for example, when an authority grants + * a credential to the account, the account owner will cosign with the authority (or authorities) to + * attach a hash of the credential to the account---hence proving the grant. If the credential is + * revoked, then any of the authorities may delete it (or the account owner). In this way, the + * livehash mechanism acts as a revocation service. An account cannot have two identical livehashes + * associated. To modify the list of keys in a livehash, the livehash should first be deleted, then + * recreated with a new list of keys. + */ message CryptoAddLiveHashTransactionBody { - // A hash of some credential or certificate, along with the keys of the entities that asserted it validity + /** + * A hash of some credential or certificate, along with the keys of the entities that asserted it validity + */ LiveHash liveHash = 3; } diff --git a/services/crypto_create.proto b/services/crypto_create.proto index c7d6b0e0..681cd982 100644 --- a/services/crypto_create.proto +++ b/services/crypto_create.proto @@ -29,23 +29,105 @@ import "basic_types.proto"; import "duration.proto"; /* -Create a new account. After the account is created, the AccountID for it is in the receipt. It can also be retrieved with a GetByKey query. Threshold values can be defined, and records are generated and stored for 25 hours for any transfer that exceeds the thresholds. This account is charged for each record generated, so the thresholds are useful for limiting record generation to happen only for large transactions. - -The Key field is the key used to sign transactions for this account. If the account has receiverSigRequired set to true, then all cryptocurrency transfers must be signed by this account's key, both for transfers in and out. If it is false, then only transfers out have to be signed by it. When the account is created, the payer account is charged enough hbars so that the new account will not expire for the next autoRenewPeriod seconds. When it reaches the expiration time, the new account will then be automatically charged to renew for another autoRenewPeriod seconds. If it does not have enough hbars to renew for that long, then the remaining hbars are used to extend its expiration as long as possible. If it is has a zero balance when it expires, then it is deleted. This transaction must be signed by the payer account. If receiverSigRequired is false, then the transaction does not have to be signed by the keys in the keys field. If it is true, then it must be signed by them, in addition to the keys of the payer account. -An entity (account, file, or smart contract instance) must be created in a particular realm. If the realmID is left null, then a new realm will be created with the given admin key. If a new realm has a null adminKey, then anyone can create/modify/delete entities in that realm. But if an admin key is given, then any transaction to create/modify/delete an entity in that realm must be signed by that key, though anyone can still call functions on smart contract instances that exist in that realm. A realm ceases to exist when everything within it has expired and no longer exists. -The current API ignores shardID, realmID, and newRealmAdminKey, and creates everything in shard 0 and realm 0, with a null key. Future versions of the API will support multiple realms and multiple shards. + * Create a new account. After the account is created, the AccountID for it is in the receipt. It + * can also be retrieved with a GetByKey query. Threshold values can be defined, and records are + * generated and stored for 25 hours for any transfer that exceeds the thresholds. This account is + * charged for each record generated, so the thresholds are useful for limiting record generation to + * happen only for large transactions. + * + * The Key field is the key used to sign transactions for this account. If the account has + * receiverSigRequired set to true, then all cryptocurrency transfers must be signed by this + * account's key, both for transfers in and out. If it is false, then only transfers out have to be + * signed by it. When the account is created, the payer account is charged enough hbars so that the + * new account will not expire for the next autoRenewPeriod seconds. When it reaches the expiration + * time, the new account will then be automatically charged to renew for another autoRenewPeriod + * seconds. If it does not have enough hbars to renew for that long, then the remaining hbars are + * used to extend its expiration as long as possible. If it is has a zero balance when it expires, + * then it is deleted. This transaction must be signed by the payer account. If receiverSigRequired + * is false, then the transaction does not have to be signed by the keys in the keys field. If it is + * true, then it must be signed by them, in addition to the keys of the payer account. + * + * An entity (account, file, or smart contract instance) must be created in a particular realm. If + * the realmID is left null, then a new realm will be created with the given admin key. If a new + * realm has a null adminKey, then anyone can create/modify/delete entities in that realm. But if an + * admin key is given, then any transaction to create/modify/delete an entity in that realm must be + * signed by that key, though anyone can still call functions on smart contract instances that exist + * in that realm. A realm ceases to exist when everything within it has expired and no longer + * exists. + * + * The current API ignores shardID, realmID, and newRealmAdminKey, and creates everything in shard 0 + * and realm 0, with a null key. Future versions of the API will support multiple realms and + * multiple shards. */ message CryptoCreateTransactionBody { - Key key = 1; // The key that must sign each transfer out of the account. If receiverSigRequired is true, then it must also sign any transfer into the account. - uint64 initialBalance = 2; // The initial number of tinybars to put into the account - AccountID proxyAccountID = 3; // ID of the account to which this account is proxy staked. If proxyAccountID is null, or is an invalid account, or is an account that isn't a node, then this account is automatically proxy staked to a node chosen by the network, but without earning payments. If the proxyAccountID account refuses to accept proxy staking , or if it is not currently running a node, then it will behave as if proxyAccountID was null. - uint64 sendRecordThreshold = 6 [deprecated=true]; // [Deprecated]. The threshold amount (in tinybars) for which an account record is created for any send/withdraw transaction - uint64 receiveRecordThreshold = 7 [deprecated=true]; // [Deprecated]. The threshold amount (in tinybars) for which an account record is created for any receive/deposit transaction - bool receiverSigRequired = 8; // If true, this account's key must sign any transaction depositing into this account (in addition to all withdrawals) - Duration autoRenewPeriod = 9; // The account is charged to extend its expiration date every this many seconds. If it doesn't have enough balance, it extends as long as possible. If it is empty when it expires, then it is deleted. - ShardID shardID = 10; // The shard in which this account is created - RealmID realmID = 11; // The realm in which this account is created (leave this null to create a new realm) - Key newRealmAdminKey = 12; // If realmID is null, then this the admin key for the new realm that will be created - string memo = 13; // The memo associated with the account (UTF-8 encoding max 100 bytes) - uint32 max_automatic_token_associations = 14; // The maximum number of tokens that an Account can be implicitly associated with. Defaults to 0 and up to a maximum value of 1000. + /** + * The key that must sign each transfer out of the account. If receiverSigRequired is true, then + * it must also sign any transfer into the account. + */ + Key key = 1; + + /** + * The initial number of tinybars to put into the account + */ + uint64 initialBalance = 2; + + /** + * ID of the account to which this account is proxy staked. If proxyAccountID is null, or is an + * invalid account, or is an account that isn't a node, then this account is automatically proxy + * staked to a node chosen by the network, but without earning payments. If the proxyAccountID + * account refuses to accept proxy staking , or if it is not currently running a node, then it + * will behave as if proxyAccountID was null. + */ + AccountID proxyAccountID = 3; + + /** + * [Deprecated]. The threshold amount (in tinybars) for which an account record is created for + * any send/withdraw transaction + */ + uint64 sendRecordThreshold = 6 [deprecated=true]; + + /** + * [Deprecated]. The threshold amount (in tinybars) for which an account record is created for + * any receive/deposit transaction + */ + uint64 receiveRecordThreshold = 7 [deprecated=true]; + + /** + * If true, this account's key must sign any transaction depositing into this account (in + * addition to all withdrawals) + */ + bool receiverSigRequired = 8; + + /** + * The account is charged to extend its expiration date every this many seconds. If it doesn't + * have enough balance, it extends as long as possible. If it is empty when it expires, then it + * is deleted. + */ + Duration autoRenewPeriod = 9; + + /** + * The shard in which this account is created + */ + ShardID shardID = 10; + + /** + * The realm in which this account is created (leave this null to create a new realm) + */ + RealmID realmID = 11; + + /** + * If realmID is null, then this the admin key for the new realm that will be created + */ + Key newRealmAdminKey = 12; + + /** + * The memo associated with the account (UTF-8 encoding max 100 bytes) + */ + string memo = 13; + + /** + * The maximum number of tokens that an Account can be implicitly associated with. Defaults to 0 + * and up to a maximum value of 1000. + */ + uint32 max_automatic_token_associations = 14; } diff --git a/services/crypto_delete.proto b/services/crypto_delete.proto index e4f78b87..6c70d12c 100644 --- a/services/crypto_delete.proto +++ b/services/crypto_delete.proto @@ -27,8 +27,19 @@ option java_multiple_files = true; import "basic_types.proto"; -/* Mark an account as deleted, moving all its current hbars to another account. It will remain in the ledger, marked as deleted, until it expires. Transfers into it a deleted account fail. But a deleted account can still have its expiration extended in the normal way. */ +/** + * Mark an account as deleted, moving all its current hbars to another account. It will remain in + * the ledger, marked as deleted, until it expires. Transfers into it a deleted account fail. But a + * deleted account can still have its expiration extended in the normal way. + */ message CryptoDeleteTransactionBody { - AccountID transferAccountID = 1; // The account ID which will receive all remaining hbars - AccountID deleteAccountID = 2; // The account ID which should be deleted + /** + * The account ID which will receive all remaining hbars + */ + AccountID transferAccountID = 1; + + /** + * The account ID which should be deleted + */ + AccountID deleteAccountID = 2; } diff --git a/services/crypto_delete_live_hash.proto b/services/crypto_delete_live_hash.proto index 55f114c3..b4850d67 100644 --- a/services/crypto_delete_live_hash.proto +++ b/services/crypto_delete_live_hash.proto @@ -27,10 +27,18 @@ option java_multiple_files = true; import "basic_types.proto"; -/* At consensus, deletes a livehash associated to the given account. The transaction must be signed by either the key of the owning account, or at least one of the keys associated to the livehash. */ +/** + * At consensus, deletes a livehash associated to the given account. The transaction must be signed + * by either the key of the owning account, or at least one of the keys associated to the livehash. + */ message CryptoDeleteLiveHashTransactionBody { - // The account owning the livehash + /** + * The account owning the livehash + */ AccountID accountOfLiveHash = 1; - // The SHA-384 livehash to delete from the account + + /** + * The SHA-384 livehash to delete from the account + */ bytes liveHashToDelete = 2; } diff --git a/services/crypto_get_account_balance.proto b/services/crypto_get_account_balance.proto index cf39d0e5..cca5944d 100644 --- a/services/crypto_get_account_balance.proto +++ b/services/crypto_get_account_balance.proto @@ -30,20 +30,53 @@ import "query_header.proto"; import "response_header.proto"; import "timestamp.proto"; -/* Get the balance of a cryptocurrency account. This returns only the balance, so it is a smaller -reply than CryptoGetInfo, which returns the balance plus additional information. */ +/** + * Get the balance of a cryptocurrency account. This returns only the balance, so it is a smaller + * reply than CryptoGetInfo, which returns the balance plus additional information. + */ message CryptoGetAccountBalanceQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + oneof balanceSource { - AccountID accountID = 2; // The account ID for which information is requested - ContractID contractID = 3; // The account ID for which information is requested + /** + * The account ID for which information is requested + */ + AccountID accountID = 2; + + /** + * The account ID for which information is requested + */ + ContractID contractID = 3; } } -/* Response when the client sends the node CryptoGetAccountBalanceQuery */ +/** + * Response when the client sends the node CryptoGetAccountBalanceQuery + */ message CryptoGetAccountBalanceResponse { - ResponseHeader header = 1; // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither. - AccountID accountID = 2; // The account ID that is being described (this is useful with state proofs, for proving to a third party) - uint64 balance = 3; // The current balance, in tinybars. - repeated TokenBalance tokenBalances = 4; // The token balances possessed by the target account. + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither. + */ + ResponseHeader header = 1; + + /** + * The account ID that is being described (this is useful with state proofs, for proving to a + * third party) + */ + AccountID accountID = 2; + + /** + * The current balance, in tinybars. + */ + uint64 balance = 3; + + /** + * The token balances possessed by the target account. + */ + repeated TokenBalance tokenBalances = 4; } diff --git a/services/crypto_get_account_records.proto b/services/crypto_get_account_records.proto index 25dd43c2..bfb7c1cf 100644 --- a/services/crypto_get_account_records.proto +++ b/services/crypto_get_account_records.proto @@ -30,17 +30,39 @@ import "transaction_record.proto"; import "query_header.proto"; import "response_header.proto"; -// Requests records of all transactions for which the given account was the effective payer in the last 3 minutes of consensus time and ledger.keepRecordsInState=true was true during handleTransaction. +/** + * Requests records of all transactions for which the given account was the effective payer in the last 3 minutes of consensus time and ledger.keepRecordsInState=true was true during handleTransaction. + */ message CryptoGetAccountRecordsQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - AccountID accountID = 2; // The account ID for which the records should be retrieved + /** + * Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The account ID for which the records should be retrieved + */ + AccountID accountID = 2; } -// Returns records of all transactions for which the given account was the effective payer in the last 3 minutes of consensus time and ledger.keepRecordsInState=true was true during handleTransaction. +/** + * Returns records of all transactions for which the given account was the effective payer in the last 3 minutes of consensus time and ledger.keepRecordsInState=true was true during handleTransaction. + */ message CryptoGetAccountRecordsResponse { - ResponseHeader header = 1; // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - AccountID accountID = 2; // The account that this record is for - repeated TransactionRecord records = 3; // List of records + /** + * Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + */ + ResponseHeader header = 1; + + /** + * The account that this record is for + */ + AccountID accountID = 2; + + /** + * List of records + */ + repeated TransactionRecord records = 3; } diff --git a/services/crypto_get_info.proto b/services/crypto_get_info.proto index d23389f3..ce80330c 100644 --- a/services/crypto_get_info.proto +++ b/services/crypto_get_info.proto @@ -32,36 +32,135 @@ import "query_header.proto"; import "response_header.proto"; import "crypto_add_live_hash.proto"; -/* Get all the information about an account, including the balance. This does not get the list of account records. */ +/** + * Get all the information about an account, including the balance. This does not get the list of + * account records. + */ message CryptoGetInfoQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - AccountID accountID = 2; // The account ID for which information is requested + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The account ID for which information is requested + */ + AccountID accountID = 2; } -/* Response when the client sends the node CryptoGetInfoQuery */ +/** + * Response when the client sends the node CryptoGetInfoQuery + */ message CryptoGetInfoResponse { - ResponseHeader header = 1; //Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + message AccountInfo { - AccountID accountID = 1; // The account ID for which this information applies - string contractAccountID = 2; // The Contract Account ID comprising of both the contract instance and the cryptocurrency account owned by the contract instance, in the format used by Solidity - bool deleted = 3; // If true, then this account has been deleted, it will disappear when it expires, and all transactions for it will fail except the transaction to extend its expiration date - AccountID proxyAccountID = 4; // The Account ID of the account to which this is proxy staked. If proxyAccountID is null, or is an invalid account, or is an account that isn't a node, then this account is automatically proxy staked to a node chosen by the network, but without earning payments. If the proxyAccountID account refuses to accept proxy staking , or if it is not currently running a node, then it will behave as if proxyAccountID was null. - int64 proxyReceived = 6; // The total number of tinybars proxy staked to this account - Key key = 7; // The key for the account, which must sign in order to transfer out, or to modify the account in any way other than extending its expiration date. - uint64 balance = 8; // The current balance of account in tinybars - // [Deprecated]. The threshold amount, in tinybars, at which a record is created of any transaction that decreases the balance of this account by more than the threshold + /** + * The account ID for which this information applies + */ + AccountID accountID = 1; + + /** + * The Contract Account ID comprising of both the contract instance and the cryptocurrency + * account owned by the contract instance, in the format used by Solidity + */ + string contractAccountID = 2; + + /** + * If true, then this account has been deleted, it will disappear when it expires, and all + * transactions for it will fail except the transaction to extend its expiration date + */ + bool deleted = 3; + + /** + * The Account ID of the account to which this is proxy staked. If proxyAccountID is null, + * or is an invalid account, or is an account that isn't a node, then this account is + * automatically proxy staked to a node chosen by the network, but without earning payments. + * If the proxyAccountID account refuses to accept proxy staking , or if it is not currently + * running a node, then it will behave as if proxyAccountID was null. + */ + AccountID proxyAccountID = 4; + + /** + * The total number of tinybars proxy staked to this account + */ + int64 proxyReceived = 6; + + /** + * The key for the account, which must sign in order to transfer out, or to modify the + * account in any way other than extending its expiration date. + */ + Key key = 7; + + /** + * The current balance of account in tinybars + */ + uint64 balance = 8; + + /** + * [Deprecated]. The threshold amount, in tinybars, at which a record is created of any + * transaction that decreases the balance of this account by more than the threshold + */ uint64 generateSendRecordThreshold = 9 [deprecated=true]; - // [Deprecated]. The threshold amount, in tinybars, at which a record is created of any transaction that increases the balance of this account by more than the threshold + + /** + * [Deprecated]. The threshold amount, in tinybars, at which a record is created of any + * transaction that increases the balance of this account by more than the threshold + */ uint64 generateReceiveRecordThreshold = 10 [deprecated=true]; - bool receiverSigRequired = 11; // If true, no transaction can transfer to this account unless signed by this account's key - Timestamp expirationTime = 12; // The TimeStamp time at which this account is set to expire - Duration autoRenewPeriod = 13; // The duration for expiration time will extend every this many seconds. If there are insufficient funds, then it extends as long as possible. If it is empty when it expires, then it is deleted. - repeated LiveHash liveHashes = 14; // All of the livehashes attached to the account (each of which is a hash along with the keys that authorized it and can delete it) - repeated TokenRelationship tokenRelationships = 15; // All tokens related to this account - string memo = 16; // The memo associated with the account - int64 ownedNfts = 17; // The number of NFTs owned by this account - uint32 max_automatic_token_associations = 18; // The maximum number of tokens that an Account can be implicitly associated with. + + /** + * If true, no transaction can transfer to this account unless signed by this account's key + */ + bool receiverSigRequired = 11; + + /** + * The TimeStamp time at which this account is set to expire + */ + Timestamp expirationTime = 12; + + /** + * The duration for expiration time will extend every this many seconds. If there are + * insufficient funds, then it extends as long as possible. If it is empty when it expires, + * then it is deleted. + */ + Duration autoRenewPeriod = 13; + + /** + * All of the livehashes attached to the account (each of which is a hash along with the + * keys that authorized it and can delete it) + */ + repeated LiveHash liveHashes = 14; + + /** + * All tokens related to this account + */ + repeated TokenRelationship tokenRelationships = 15; + + /** + * The memo associated with the account + */ + string memo = 16; + + /** + * The number of NFTs owned by this account + */ + int64 ownedNfts = 17; + + /** + * The maximum number of tokens that an Account can be implicitly associated with. + */ + uint32 max_automatic_token_associations = 18; } - AccountInfo accountInfo = 2; // Info about the account (a state proof can be generated for this) + + /** + * Info about the account (a state proof can be generated for this) + */ + AccountInfo accountInfo = 2; } diff --git a/services/crypto_get_live_hash.proto b/services/crypto_get_live_hash.proto index 78994dec..f1299e48 100644 --- a/services/crypto_get_live_hash.proto +++ b/services/crypto_get_live_hash.proto @@ -30,21 +30,42 @@ import "query_header.proto"; import "response_header.proto"; import "crypto_add_live_hash.proto"; -/* Requests a livehash associated to an account. */ +/** + * Requests a livehash associated to an account. + */ message CryptoGetLiveHashQuery { - // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ QueryHeader header = 1; - // The account to which the livehash is associated + + /** + * The account to which the livehash is associated + */ AccountID accountID = 2; - // The SHA-384 data in the livehash + + /** + * The SHA-384 data in the livehash + */ bytes hash = 3; } -/* Returns the full livehash associated to an account, if it is present. Note that the only way to obtain a state proof exhibiting the absence of a livehash from an account is to retrieve a state proof of the entire account with its list of livehashes. */ +/** + * Returns the full livehash associated to an account, if it is present. Note that the only way to + * obtain a state proof exhibiting the absence of a livehash from an account is to retrieve a state + * proof of the entire account with its list of livehashes. + */ message CryptoGetLiveHashResponse { - // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ ResponseHeader header = 1; - // The livehash, if present + + /** + * The livehash, if present + */ LiveHash liveHash = 2; } diff --git a/services/crypto_get_stakers.proto b/services/crypto_get_stakers.proto index d5331089..6184fa52 100644 --- a/services/crypto_get_stakers.proto +++ b/services/crypto_get_stakers.proto @@ -29,25 +29,66 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* Get all the accounts that are proxy staking to this account. For each of them, give the amount currently staked. This is not yet implemented, but will be in a future version of the API. */ +/** + * Get all the accounts that are proxy staking to this account. For each of them, give the amount + * currently staked. This is not yet implemented, but will be in a future version of the API. + */ message CryptoGetStakersQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - AccountID accountID = 2; // The Account ID for which the records should be retrieved + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The Account ID for which the records should be retrieved + */ + AccountID accountID = 2; } -/* information about a single account that is proxy staking */ +/** + * information about a single account that is proxy staking + */ message ProxyStaker { - AccountID accountID = 1; // The Account ID that is proxy staking - int64 amount = 2; // The number of hbars that are currently proxy staked + /** + * The Account ID that is proxy staking + */ + AccountID accountID = 1; + + /** + * The number of hbars that are currently proxy staked + */ + int64 amount = 2; } -/* all of the accounts proxy staking to a given account, and the amounts proxy staked */ +/** + * all of the accounts proxy staking to a given account, and the amounts proxy staked + */ message AllProxyStakers { - AccountID accountID = 1; // The Account ID that is being proxy staked to - repeated ProxyStaker proxyStaker = 2; // Each of the proxy staking accounts, and the amount they are proxy staking + /** + * The Account ID that is being proxy staked to + */ + AccountID accountID = 1; + + /** + * Each of the proxy staking accounts, and the amount they are proxy staking + */ + repeated ProxyStaker proxyStaker = 2; } -/* Response when the client sends the node CryptoGetStakersQuery */ + +/** + * Response when the client sends the node CryptoGetStakersQuery + */ message CryptoGetStakersResponse { - ResponseHeader header = 1; //Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - AllProxyStakers stakers = 3; // List of accounts proxy staking to this account, and the amount each is currently proxy staking + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + + /** + * List of accounts proxy staking to this account, and the amount each is currently proxy + * staking + */ + AllProxyStakers stakers = 3; } diff --git a/services/crypto_service.proto b/services/crypto_service.proto index 259b5639..2e035c1d 100644 --- a/services/crypto_service.proto +++ b/services/crypto_service.proto @@ -28,36 +28,81 @@ import "response.proto"; import "transaction_response.proto"; import "transaction.proto"; -/* -Transactions and queries for the Crypto Service -*/ +/** + * Transactions and queries for the Crypto Service + */ service CryptoService { - // Creates a new account by submitting the transaction + /** + * Creates a new account by submitting the transaction + */ rpc createAccount (Transaction) returns (TransactionResponse); - // Updates an account by submitting the transaction + + /** + * Updates an account by submitting the transaction + */ rpc updateAccount (Transaction) returns (TransactionResponse); - // Initiates a transfer by submitting the transaction + + /** + * Initiates a transfer by submitting the transaction + */ rpc cryptoTransfer (Transaction) returns (TransactionResponse); - // Deletes and account by submitting the transaction + + /** + * Deletes and account by submitting the transaction + */ rpc cryptoDelete (Transaction) returns (TransactionResponse); - // (NOT CURRENTLY SUPPORTED) Adds a livehash + + /** + * (NOT CURRENTLY SUPPORTED) Adds a livehash + */ rpc addLiveHash (Transaction) returns (TransactionResponse); - // (NOT CURRENTLY SUPPORTED) Deletes a livehash + + /** + * (NOT CURRENTLY SUPPORTED) Deletes a livehash + */ rpc deleteLiveHash (Transaction) returns (TransactionResponse); - // (NOT CURRENTLY SUPPORTED) Retrieves a livehash for an account + + /** + * (NOT CURRENTLY SUPPORTED) Retrieves a livehash for an account + */ rpc getLiveHash (Query) returns (Response); - // Returns all transactions in the last 180s of consensus time for which the given account was the effective payer and network property ledger.keepRecordsInState was true. + + /** + * Returns all transactions in the last 180s of consensus time for which the given account was + * the effective payer and network property ledger.keepRecordsInState was + * true. + */ rpc getAccountRecords (Query) returns (Response); - // Retrieves the balance of an account + + /** + * Retrieves the balance of an account + */ rpc cryptoGetBalance (Query) returns (Response); - // Retrieves the metadata of an account + + /** + * Retrieves the metadata of an account + */ rpc getAccountInfo (Query) returns (Response); - // Retrieves the latest receipt for a transaction that is either awaiting consensus, or reached consensus in the last 180 seconds + + /** + * Retrieves the latest receipt for a transaction that is either awaiting consensus, or reached + * consensus in the last 180 seconds + */ rpc getTransactionReceipts (Query) returns (Response); - // (NOT CURRENTLY SUPPORTED) Returns the records of transactions recently funded by an account + + /** + * (NOT CURRENTLY SUPPORTED) Returns the records of transactions recently funded by an account + */ rpc getFastTransactionRecord (Query) returns (Response); - // Retrieves the record of a transaction that is either awaiting consensus, or reached consensus in the last 180 seconds + + /** + * Retrieves the record of a transaction that is either awaiting consensus, or reached consensus + * in the last 180 seconds + */ rpc getTxRecordByTxID (Query) returns (Response); - // (NOT CURRENTLY SUPPORTED) Retrieves the stakers for a node by account id + + /** + * (NOT CURRENTLY SUPPORTED) Retrieves the stakers for a node by account id + */ rpc getStakersByAccountID (Query) returns (Response); } diff --git a/services/crypto_transfer.proto b/services/crypto_transfer.proto index 565421ff..0271419a 100644 --- a/services/crypto_transfer.proto +++ b/services/crypto_transfer.proto @@ -27,10 +27,27 @@ option java_multiple_files = true; import "basic_types.proto"; -/* Transfers cryptocurrency among two or more accounts by making the desired adjustments to their balances. Each transfer list can specify up to 10 adjustments. Each negative amount is withdrawn from the corresponding account (a sender), and each positive one is added to the corresponding account (a receiver). The amounts list must sum to zero. Each amount is a number of tinybars (there are 100,000,000 tinybars in one hbar). -If any sender account fails to have sufficient hbars, then the entire transaction fails, and none of those transfers occur, though the transaction fee is still charged. This transaction must be signed by the keys for all the sending accounts, and for any receiving accounts that have receiverSigRequired == true. The signatures are in the same order as the accounts, skipping those accounts that don't need a signature. -*/ +/** + * Transfers cryptocurrency among two or more accounts by making the desired adjustments to their + * balances. Each transfer list can specify up to 10 adjustments. Each negative amount is withdrawn + * from the corresponding account (a sender), and each positive one is added to the corresponding + * account (a receiver). The amounts list must sum to zero. Each amount is a number of tinybars + * (there are 100,000,000 tinybars in one hbar). If any sender account fails to have sufficient + * hbars, then the entire transaction fails, and none of those transfers occur, though the + * transaction fee is still charged. This transaction must be signed by the keys for all the sending + * accounts, and for any receiving accounts that have receiverSigRequired == true. The signatures + * are in the same order as the accounts, skipping those accounts that don't need a signature. + */ message CryptoTransferTransactionBody { - TransferList transfers = 1; // The desired hbar balance adjustments - repeated TokenTransferList tokenTransfers = 2; // The desired token unit balance adjustments; if any custom fees are assessed, the ledger will try to deduct them from the payer of this CryptoTransfer, resolving the transaction to INSUFFICIENT_PAYER_BALANCE_FOR_CUSTOM_FEE if this is not possible + /** + * The desired hbar balance adjustments + */ + TransferList transfers = 1; + + /** + * The desired token unit balance adjustments; if any custom fees are assessed, the ledger will + * try to deduct them from the payer of this CryptoTransfer, resolving the transaction to + * INSUFFICIENT_PAYER_BALANCE_FOR_CUSTOM_FEE if this is not possible + */ + repeated TokenTransferList tokenTransfers = 2; } diff --git a/services/crypto_update.proto b/services/crypto_update.proto index 447c6621..97884f0d 100644 --- a/services/crypto_update.proto +++ b/services/crypto_update.proto @@ -30,28 +30,103 @@ import "duration.proto"; import "timestamp.proto"; import "google/protobuf/wrappers.proto"; -/* -Change properties for the given account. Any null field is ignored (left unchanged). This transaction must be signed by the existing key for this account. If the transaction is changing the key field, then the transaction must be signed by both the old key (from before the change) and the new key. The old key must sign for security. The new key must sign as a safeguard to avoid accidentally changing to an invalid key, and then having no way to recover. -*/ +/** + * Change properties for the given account. Any null field is ignored (left unchanged). This + * transaction must be signed by the existing key for this account. If the transaction is changing + * the key field, then the transaction must be signed by both the old key (from before the change) + * and the new key. The old key must sign for security. The new key must sign as a safeguard to + * avoid accidentally changing to an invalid key, and then having no way to recover. + */ message CryptoUpdateTransactionBody { - AccountID accountIDToUpdate = 2; // The account ID which is being updated in this transaction - Key key = 3; // The new key - AccountID proxyAccountID = 4; // ID of the account to which this account is proxy staked. If proxyAccountID is null, or is an invalid account, or is an account that isn't a node, then this account is automatically proxy staked to a node chosen by the network, but without earning payments. If the proxyAccountID account refuses to accept proxy staking , or if it is not currently running a node, then it will behave as if proxyAccountID was null. - int32 proxyFraction = 5 [deprecated = true]; // [Deprecated]. Payments earned from proxy staking are shared between the node and this account, with proxyFraction / 10000 going to this account + /** + * The account ID which is being updated in this transaction + */ + AccountID accountIDToUpdate = 2; + + /** + * The new key + */ + Key key = 3; + + /** + * ID of the account to which this account is proxy staked. If proxyAccountID is null, or is an + * invalid account, or is an account that isn't a node, then this account is automatically proxy + * staked to a node chosen by the network, but without earning payments. If the proxyAccountID + * account refuses to accept proxy staking , or if it is not currently running a node, then it + * will behave as if proxyAccountID was null. + */ + AccountID proxyAccountID = 4; + + /** + * [Deprecated]. Payments earned from proxy staking are shared between the node and this + * account, with proxyFraction / 10000 going to this account + */ + int32 proxyFraction = 5 [deprecated = true]; + oneof sendRecordThresholdField { - uint64 sendRecordThreshold = 6 [deprecated = true]; // [Deprecated]. The new threshold amount (in tinybars) for which an account record is created for any send/withdraw transaction - google.protobuf.UInt64Value sendRecordThresholdWrapper = 11 [deprecated = true]; // [Deprecated]. The new threshold amount (in tinybars) for which an account record is created for any send/withdraw transaction + /** + * [Deprecated]. The new threshold amount (in tinybars) for which an account record is + * created for any send/withdraw transaction + */ + uint64 sendRecordThreshold = 6 [deprecated = true]; + + /** + * [Deprecated]. The new threshold amount (in tinybars) for which an account record is + * created for any send/withdraw transaction + */ + google.protobuf.UInt64Value sendRecordThresholdWrapper = 11 [deprecated = true]; + } + oneof receiveRecordThresholdField { - uint64 receiveRecordThreshold = 7 [deprecated = true]; // [Deprecated]. The new threshold amount (in tinybars) for which an account record is created for any receive/deposit transaction. - google.protobuf.UInt64Value receiveRecordThresholdWrapper = 12 [deprecated = true]; // [Deprecated]. The new threshold amount (in tinybars) for which an account record is created for any receive/deposit transaction. + /** + * [Deprecated]. The new threshold amount (in tinybars) for which an account record is + * created for any receive/deposit transaction. + */ + uint64 receiveRecordThreshold = 7 [deprecated = true]; + + /** + * [Deprecated]. The new threshold amount (in tinybars) for which an account record is + * created for any receive/deposit transaction. + */ + google.protobuf.UInt64Value receiveRecordThresholdWrapper = 12 [deprecated = true]; } - Duration autoRenewPeriod = 8; // The duration in which it will automatically extend the expiration period. If it doesn't have enough balance, it extends as long as possible. If it is empty when it expires, then it is deleted. - Timestamp expirationTime = 9; // The new expiration time to extend to (ignored if equal to or before the current one) + + /** + * The duration in which it will automatically extend the expiration period. If it doesn't have + * enough balance, it extends as long as possible. If it is empty when it expires, then it is + * deleted. + */ + Duration autoRenewPeriod = 8; + + /** + * The new expiration time to extend to (ignored if equal to or before the current one) + */ + Timestamp expirationTime = 9; + oneof receiverSigRequiredField { - bool receiverSigRequired = 10 [deprecated = true]; // [Deprecated] Do NOT use this field to set a false value because the server cannot distinguish from the default value. Use receiverSigRequiredWrapper field for this purpose. - google.protobuf.BoolValue receiverSigRequiredWrapper = 13; // If true, this account's key must sign any transaction depositing into this account (in addition to all withdrawals) + /** + * [Deprecated] Do NOT use this field to set a false value because the server cannot + * distinguish from the default value. Use receiverSigRequiredWrapper field for this + * purpose. + */ + bool receiverSigRequired = 10 [deprecated = true]; + + /** + * If true, this account's key must sign any transaction depositing into this account (in + * addition to all withdrawals) + */ + google.protobuf.BoolValue receiverSigRequiredWrapper = 13; } - google.protobuf.StringValue memo = 14; // If set, the new memo to be associated with the account (UTF-8 encoding max 100 bytes) - google.protobuf.UInt32Value max_automatic_token_associations = 15; // The maximum number of tokens that an Account can be implicitly associated with. Up to a 1000 including implicit and explicit associations. + + /** + * If set, the new memo to be associated with the account (UTF-8 encoding max 100 bytes) + */ + google.protobuf.StringValue memo = 14; + + /** + * The maximum number of tokens that an Account can be implicitly associated with. Up to a 1000 + * including implicit and explicit associations. + */ + google.protobuf.UInt32Value max_automatic_token_associations = 15; } diff --git a/services/custom_fees.proto b/services/custom_fees.proto index 9d0720cd..23ce3065 100644 --- a/services/custom_fees.proto +++ b/services/custom_fees.proto @@ -27,50 +27,122 @@ option java_multiple_files = true; import "basic_types.proto"; -/* A fraction of the transferred units of a token to assess as a fee. The amount assessed -will never be less than the given minimum_amount, and never greater than the given maximum_amount. -The denomination is always units of the token to which this fractional fee is attached. */ +/** + * A fraction of the transferred units of a token to assess as a fee. The amount assessed will never + * be less than the given minimum_amount, and never greater than the given maximum_amount. The + * denomination is always units of the token to which this fractional fee is attached. + */ message FractionalFee { - Fraction fractional_amount = 1; // The fraction of the transferred units to assess as a fee - int64 minimum_amount = 2; // The minimum amount to assess - int64 maximum_amount = 3; // The maximum amount to assess (zero implies no maximum) - bool net_of_transfers = 4; // If true, assesses the fee to the sender, so the receiver gets the full amount from the token transfer list, and the sender is charged an additional fee; if false, the receiver does NOT get the full amount, but only what is left over after paying the fractional fee + /** + * The fraction of the transferred units to assess as a fee + */ + Fraction fractional_amount = 1; + + /** + * The minimum amount to assess + */ + int64 minimum_amount = 2; + + /** + * The maximum amount to assess (zero implies no maximum) + */ + int64 maximum_amount = 3; + + /** + * If true, assesses the fee to the sender, so the receiver gets the full amount from the token + * transfer list, and the sender is charged an additional fee; if false, the receiver does NOT get + * the full amount, but only what is left over after paying the fractional fee + */ + bool net_of_transfers = 4; } -/* A fixed number of units (hbar or token) to assess as a fee during a CryptoTransfer -that transfers units of the token to which this fixed fee is attached. */ +/** + * A fixed number of units (hbar or token) to assess as a fee during a CryptoTransfer that transfers + * units of the token to which this fixed fee is attached. + */ message FixedFee { - int64 amount = 1; // The number of units to assess as a fee - TokenID denominating_token_id = 2; // The denomination of the fee; taken as hbar if left unset and, in a TokenCreate, taken as the id of the newly created token if set to the sentinel value of 0.0.0 + /** + * The number of units to assess as a fee + */ + int64 amount = 1; + + /** + * The denomination of the fee; taken as hbar if left unset and, in a TokenCreate, taken as the id + * of the newly created token if set to the sentinel value of 0.0.0 + */ + TokenID denominating_token_id = 2; } -/* A fee to assess during a CryptoTransfer that changes ownership of an NFT. Defines -the fraction of the fungible value exchanged for an NFT that the ledger should collect -as a royalty. ("Fungible value" includes both ℏ and units of fungible HTS tokens.) When -the NFT sender does not receive any fungible value, the ledger will assess the fallback -fee, if present, to the new NFT owner. Royalty fees can only be added to tokens of type -type NON_FUNGIBLE_UNIQUE. */ +/** + * A fee to assess during a CryptoTransfer that changes ownership of an NFT. Defines the fraction of + * the fungible value exchanged for an NFT that the ledger should collect as a royalty. ("Fungible + * value" includes both ℏ and units of fungible HTS tokens.) When the NFT sender does not receive + * any fungible value, the ledger will assess the fallback fee, if present, to the new NFT owner. + * Royalty fees can only be added to tokens of type type NON_FUNGIBLE_UNIQUE. + */ message RoyaltyFee { - Fraction exchange_value_fraction = 1; // The fraction of fungible value exchanged for an NFT to collect as royalty - FixedFee fallback_fee = 2; // If present, the fixed fee to assess to the NFT receiver when no fungible value is exchanged with the sender + /** + * The fraction of fungible value exchanged for an NFT to collect as royalty + */ + Fraction exchange_value_fraction = 1; + + /** + * If present, the fixed fee to assess to the NFT receiver when no fungible value is exchanged + * with the sender + */ + FixedFee fallback_fee = 2; } -/* A transfer fee to assess during a CryptoTransfer that transfers units of the token -to which the fee is attached. A custom fee may be either fixed or fractional, and must specify -a fee collector account to receive the assessed fees. Only positive fees may be assessed. */ +/** + * A transfer fee to assess during a CryptoTransfer that transfers units of the token to which the + * fee is attached. A custom fee may be either fixed or fractional, and must specify a fee collector + * account to receive the assessed fees. Only positive fees may be assessed. + */ message CustomFee { oneof fee { - FixedFee fixed_fee = 1; // Fixed fee to be charged - FractionalFee fractional_fee = 2; // Fractional fee to be charged - RoyaltyFee royalty_fee = 4; // Royalty fee to be charged + /** + * Fixed fee to be charged + */ + FixedFee fixed_fee = 1; + + /** + * Fractional fee to be charged + */ + FractionalFee fractional_fee = 2; + + /** + * Royalty fee to be charged + */ + RoyaltyFee royalty_fee = 4; + } - AccountID fee_collector_account_id = 3; // The account to receive the custom fee + /** + * The account to receive the custom fee + */ + AccountID fee_collector_account_id = 3; } -/* A custom transfer fee that was assessed during handling of a CryptoTransfer. */ +/** + * A custom transfer fee that was assessed during handling of a CryptoTransfer. + */ message AssessedCustomFee { - int64 amount = 1; // The number of units assessed for the fee - TokenID token_id = 2; // The denomination of the fee; taken as hbar if left unset - AccountID fee_collector_account_id = 3; // The account to receive the assessed fee - repeated AccountID effective_payer_account_id = 4; // The account(s) whose final balances would have been higher in the absence of this assessed fee + /** + * The number of units assessed for the fee + */ + int64 amount = 1; + + /** + * The denomination of the fee; taken as hbar if left unset + */ + TokenID token_id = 2; + + /** + * The account to receive the assessed fee + */ + AccountID fee_collector_account_id = 3; + + /** + * The account(s) whose final balances would have been higher in the absence of this assessed fee + */ + repeated AccountID effective_payer_account_id = 4; } diff --git a/services/duration.proto b/services/duration.proto index 4d3c362c..f01f4b88 100644 --- a/services/duration.proto +++ b/services/duration.proto @@ -25,7 +25,12 @@ package proto; option java_package = "com.hederahashgraph.api.proto.java"; option java_multiple_files = true; -/* A length of time in seconds. */ +/** + * A length of time in seconds. + */ message Duration { - int64 seconds = 1; // The number of seconds + /** + * The number of seconds + */ + int64 seconds = 1; } diff --git a/services/exchange_rate.proto b/services/exchange_rate.proto index 2680e950..1a7b9cc5 100644 --- a/services/exchange_rate.proto +++ b/services/exchange_rate.proto @@ -27,21 +27,38 @@ option java_multiple_files = true; import "timestamp.proto"; -/* -An exchange rate between hbar and cents (USD) and the time at which the exchange rate will expire, and be superseded by a new exchange rate. -*/ +/** + * An exchange rate between hbar and cents (USD) and the time at which the exchange rate will + * expire, and be superseded by a new exchange rate. + */ message ExchangeRate { - // Denominator in calculation of exchange rate between hbar and cents + /** + * Denominator in calculation of exchange rate between hbar and cents + */ int32 hbarEquiv = 1; - // Numerator in calculation of exchange rate between hbar and cents + + /** + * Numerator in calculation of exchange rate between hbar and cents + */ int32 centEquiv = 2; - // Expiration time in seconds for this exchange rate + + /** + * Expiration time in seconds for this exchange rate + */ TimestampSeconds expirationTime = 3; } -/* Two sets of exchange rates */ + +/** + * Two sets of exchange rates + */ message ExchangeRateSet { - // Current exchange rate + /** + * Current exchange rate + */ ExchangeRate currentRate = 1; - // Next exchange rate which will take effect when current rate expires + + /** + * Next exchange rate which will take effect when current rate expires + */ ExchangeRate nextRate = 2; } diff --git a/services/file_append.proto b/services/file_append.proto index f5148277..dc3206c4 100644 --- a/services/file_append.proto +++ b/services/file_append.proto @@ -28,12 +28,21 @@ option java_multiple_files = true; import "basic_types.proto"; -/* -Append the given contents to the end of the specified file. If a file is too big to create with a single FileCreateTransaction, then it can be created with the first part of its contents, and then appended as many times as necessary to create the entire file. This transaction must be signed by all initial M-of-M KeyList keys. If keys contains additional KeyList or ThresholdKey then M-of-M secondary KeyList or ThresholdKey signing requirements must be meet. -*/ +/** + * Append the given contents to the end of the specified file. If a file is too big to create with a + * single FileCreateTransaction, then it can be created with the first part of its contents, and + * then appended as many times as necessary to create the entire file. This transaction must be + * signed by all initial M-of-M KeyList keys. If keys contains additional KeyList or ThresholdKey + * then M-of-M secondary KeyList or ThresholdKey signing requirements must be meet. + */ message FileAppendTransactionBody { - // The file to which the bytes will be appended + /** + * The file to which the bytes will be appended + */ FileID fileID = 2; - // The bytes that will be appended to the end of the specified file + + /** + * The bytes that will be appended to the end of the specified file + */ bytes contents = 4; } diff --git a/services/file_create.proto b/services/file_create.proto index 4467d6f4..e3abf183 100644 --- a/services/file_create.proto +++ b/services/file_create.proto @@ -28,26 +28,75 @@ option java_multiple_files = true; import "basic_types.proto"; import "timestamp.proto"; -/* Create a new file, containing the given contents. -After the file is created, the FileID for it can be found in the receipt, or record, or retrieved with a GetByKey query. +/** + * Create a new file, containing the given contents. + * After the file is created, the FileID for it can be found in the receipt, or record, or retrieved + * with a GetByKey query. + * + * The file contains the specified contents (possibly empty). The file will automatically disappear + * at the expirationTime, unless its expiration is extended by another transaction before that time. + * If the file is deleted, then its contents will become empty and it will be marked as deleted + * until it expires, and then it will cease to exist. + * + * The keys field is a list of keys. All keys within the top-level key list must sign (M-M) to + * create or modify a file. However, to delete the file, only one key (1-M) is required to sign from + * the top-level key list. Each of those "keys" may itself be threshold key containing other keys + * (including other threshold keys). In other words, the behavior is an AND for create/modify, OR + * for delete. This is useful for acting as a revocation server. If it is desired to have the + * behavior be AND for all 3 operations (or OR for all 3), then the list should have only a single + * Key, which is a threshold key, with N=1 for OR, N=M for AND. + * + * If a file is created without ANY keys in the keys field, the file is immutable and ONLY the + * expirationTime of the file can be changed with a FileUpdate transaction. The file contents or its + * keys cannot be changed. + * + * An entity (account, file, or smart contract instance) must be created in a particular realm. If + * the realmID is left null, then a new realm will be created with the given admin key. If a new + * realm has a null adminKey, then anyone can create/modify/delete entities in that realm. But if an + * admin key is given, then any transaction to create/modify/delete an entity in that realm must be + * signed by that key, though anyone can still call functions on smart contract instances that exist + * in that realm. A realm ceases to exist when everything within it has expired and no longer + * exists. + * + * The current API ignores shardID, realmID, and newRealmAdminKey, and creates everything in shard 0 + * and realm 0, with a null key. Future versions of the API will support multiple realms and + * multiple shards. + */ +message FileCreateTransactionBody { + /** + * The time at which this file should expire (unless FileUpdateTransaction is used before then + * to extend its life) + */ + Timestamp expirationTime = 2; - The file contains the specified contents (possibly empty). The file will automatically disappear at the expirationTime, unless its expiration is extended by another transaction before that time. If the file is deleted, then its contents will become empty and it will be marked as deleted until it expires, and then it will cease to exist. + /** + * All keys at the top level of a key list must sign to create or modify the file. Any one of + * the keys at the top level key list can sign to delete the file. + */ + KeyList keys = 3; - The keys field is a list of keys. All keys within the top-level key list must sign (M-M) to create or modify a file. However, to delete the file, only one key (1-M) is required to sign from the top-level key list. Each of those "keys" may itself be threshold key containing other keys (including other threshold keys). In other words, the behavior is an AND for create/modify, OR for delete. This is useful for acting as a revocation server. If it is desired to have the behavior be AND for all 3 operations (or OR for all 3), then the list should have only a single Key, which is a threshold key, with N=1 for OR, N=M for AND. + /** + * The bytes that are the contents of the file + */ + bytes contents = 4; - If a file is created without ANY keys in the keys field, the file is immutable and ONLY the expirationTime of the file can be changed with a FileUpdate transaction. The file contents or its keys cannot be changed. + /** + * Shard in which this file is created + */ + ShardID shardID = 5; - An entity (account, file, or smart contract instance) must be created in a particular realm. If the realmID is left null, then a new realm will be created with the given admin key. If a new realm has a null adminKey, then anyone can create/modify/delete entities in that realm. But if an admin key is given, then any transaction to create/modify/delete an entity in that realm must be signed by that key, though anyone can still call functions on smart contract instances that exist in that realm. A realm ceases to exist when everything within it has expired and no longer exists. + /** + * The Realm in which to the file is created (leave this null to create a new realm) + */ + RealmID realmID = 6; - The current API ignores shardID, realmID, and newRealmAdminKey, and creates everything in shard 0 and realm 0, with a null key. Future versions of the API will support multiple realms and multiple shards. - */ -message FileCreateTransactionBody { - Timestamp expirationTime = 2; // The time at which this file should expire (unless FileUpdateTransaction is used before then to extend its life) - KeyList keys = 3; // All keys at the top level of a key list must sign to create or modify the file. Any one of the keys at the top level key list can sign to delete the file. - bytes contents = 4; // The bytes that are the contents of the file - - ShardID shardID = 5; // Shard in which this file is created - RealmID realmID = 6; // The Realm in which to the file is created (leave this null to create a new realm) - Key newRealmAdminKey = 7; // If realmID is null, then this the admin key for the new realm that will be created - string memo = 8; // The memo associated with the file (UTF-8 encoding max 100 bytes) + /** + * If realmID is null, then this the admin key for the new realm that will be created + */ + Key newRealmAdminKey = 7; + + /** + * The memo associated with the file (UTF-8 encoding max 100 bytes) + */ + string memo = 8; } diff --git a/services/file_delete.proto b/services/file_delete.proto index f0ddda21..5d9a3126 100644 --- a/services/file_delete.proto +++ b/services/file_delete.proto @@ -27,7 +27,17 @@ option java_multiple_files = true; import "basic_types.proto"; -/* Delete the given file. After deletion, it will be marked as deleted and will have no contents. But information about it will continue to exist until it expires. A list of keys was given when the file was created. All the top level keys on that list must sign transactions to create or modify the file, but any single one of the top level keys can be used to delete the file. This transaction must be signed by 1-of-M KeyList keys. If keys contains additional KeyList or ThresholdKey then 1-of-M secondary KeyList or ThresholdKey signing requirements must be meet. */ +/** + * Delete the given file. After deletion, it will be marked as deleted and will have no contents. + * But information about it will continue to exist until it expires. A list of keys was given when + * the file was created. All the top level keys on that list must sign transactions to create or + * modify the file, but any single one of the top level keys can be used to delete the file. This + * transaction must be signed by 1-of-M KeyList keys. If keys contains additional KeyList or + * ThresholdKey then 1-of-M secondary KeyList or ThresholdKey signing requirements must be meet. + */ message FileDeleteTransactionBody { - FileID fileID = 2; // The file to delete. It will be marked as deleted until it expires. Then it will disappear. + /** + * The file to delete. It will be marked as deleted until it expires. Then it will disappear. + */ + FileID fileID = 2; } diff --git a/services/file_get_contents.proto b/services/file_get_contents.proto index 872d9a45..fc6e9a1a 100644 --- a/services/file_get_contents.proto +++ b/services/file_get_contents.proto @@ -29,20 +29,48 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* Get the contents of a file. The content field is empty (no bytes) if the file is empty. */ +/** + * Get the contents of a file. The content field is empty (no bytes) if the file is empty. + */ message FileGetContentsQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - FileID fileID = 2; // The file ID of the file whose contents are requested + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The file ID of the file whose contents are requested + */ + FileID fileID = 2; } -/* Response when the client sends the node FileGetContentsQuery */ +/** + * Response when the client sends the node FileGetContentsQuery + */ message FileGetContentsResponse { - ResponseHeader header = 1; //Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + message FileContents { - FileID fileID = 1; // The file ID of the file whose contents are being returned - bytes contents = 2; // The bytes contained in the file + /** + * The file ID of the file whose contents are being returned + */ + FileID fileID = 1; + + /** + * The bytes contained in the file + */ + bytes contents = 2; } - FileContents fileContents = 2; // the file ID and contents (a state proof can be generated for this) + + /** + * the file ID and contents (a state proof can be generated for this) + */ + FileContents fileContents = 2; } diff --git a/services/file_get_info.proto b/services/file_get_info.proto index 1a7bf2e2..666f1ecb 100644 --- a/services/file_get_info.proto +++ b/services/file_get_info.proto @@ -30,23 +30,71 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* Get all of the information about a file, except for its contents. When a file expires, it no longer exists, and there will be no info about it, and the fileInfo field will be blank. If a transaction or smart contract deletes the file, but it has not yet expired, then the fileInfo field will be non-empty, the deleted field will be true, its size will be 0, and its contents will be empty. */ +/** + * Get all of the information about a file, except for its contents. When a file expires, it no + * longer exists, and there will be no info about it, and the fileInfo field will be blank. If a + * transaction or smart contract deletes the file, but it has not yet expired, then the fileInfo + * field will be non-empty, the deleted field will be true, its size will be 0, and its contents + * will be empty. + */ message FileGetInfoQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - FileID fileID = 2; // The file ID of the file for which information is requested + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The file ID of the file for which information is requested + */ + FileID fileID = 2; } -/* Response when the client sends the node FileGetInfoQuery */ +/** + * Response when the client sends the node FileGetInfoQuery + */ message FileGetInfoResponse { - ResponseHeader header = 1; //Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + message FileInfo { - FileID fileID = 1; // The file ID of the file for which information is requested - int64 size = 2; // Number of bytes in contents - Timestamp expirationTime = 3; // The current time at which this account is set to expire - bool deleted = 4; // True if deleted but not yet expired - KeyList keys = 5; // One of these keys must sign in order to modify or delete the file - string memo = 6; // The memo associated with the file + /** + * The file ID of the file for which information is requested + */ + FileID fileID = 1; + + /** + * Number of bytes in contents + */ + int64 size = 2; + + /** + * The current time at which this account is set to expire + */ + Timestamp expirationTime = 3; + + /** + * True if deleted but not yet expired + */ + bool deleted = 4; + + /** + * One of these keys must sign in order to modify or delete the file + */ + KeyList keys = 5; + + /** + * The memo associated with the file + */ + string memo = 6; } - FileInfo fileInfo = 2; // The information about the file + + /** + * The information about the file + */ + FileInfo fileInfo = 2; } diff --git a/services/file_service.proto b/services/file_service.proto index e0d2399a..9e9a949b 100644 --- a/services/file_service.proto +++ b/services/file_service.proto @@ -28,24 +28,47 @@ import "response.proto"; import "transaction_response.proto"; import "transaction.proto"; -/* -Transactions and queries for the file service. -*/ +/** + * Transactions and queries for the file service. + */ service FileService { - // Creates a file + /** + * Creates a file + */ rpc createFile (Transaction) returns (TransactionResponse); - // Updates a file + + /** + * Updates a file + */ rpc updateFile (Transaction) returns (TransactionResponse); - // Deletes a file + + /** + * Deletes a file + */ rpc deleteFile (Transaction) returns (TransactionResponse); - // Appends to a file + + /** + * Appends to a file + */ rpc appendContent (Transaction) returns (TransactionResponse); - // Retrieves the file contents + + /** + * Retrieves the file contents + */ rpc getFileContent (Query) returns (Response); - // Retrieves the file information + + /** + * Retrieves the file information + */ rpc getFileInfo (Query) returns (Response); - // Deletes a file if the submitting account has network admin privileges + + /** + * Deletes a file if the submitting account has network admin privileges + */ rpc systemDelete (Transaction) returns (TransactionResponse); - // Undeletes a file if the submitting account has network admin privileges + + /** + * Undeletes a file if the submitting account has network admin privileges + */ rpc systemUndelete (Transaction) returns (TransactionResponse); } diff --git a/services/file_update.proto b/services/file_update.proto index 8be23026..411e143d 100644 --- a/services/file_update.proto +++ b/services/file_update.proto @@ -29,13 +29,37 @@ import "basic_types.proto"; import "timestamp.proto"; import "google/protobuf/wrappers.proto"; -/* -Modify the metadata and/or contents of a file. If a field is not set in the transaction body, the corresponding file attribute will be unchanged. This transaction must be signed by all the keys in the top level of a key list (M-of-M) of the file being updated. If the keys themselves are being updated, then the transaction must also be signed by all the new keys. If the keys contain additional KeyList or ThresholdKey then M-of-M secondary KeyList or ThresholdKey signing requirements must be meet +/** + * Modify the metadata and/or contents of a file. If a field is not set in the transaction body, the + * corresponding file attribute will be unchanged. This transaction must be signed by all the keys + * in the top level of a key list (M-of-M) of the file being updated. If the keys themselves are + * being updated, then the transaction must also be signed by all the new keys. If the keys contain + * additional KeyList or ThresholdKey then M-of-M secondary KeyList or ThresholdKey signing + * requirements must be meet */ message FileUpdateTransactionBody { - FileID fileID = 1; // The ID of the file to update - Timestamp expirationTime = 2; // The new expiry time (ignored if not later than the current expiry) - KeyList keys = 3; // The new list of keys that can modify or delete the file - bytes contents = 4; // The new contents that should overwrite the file's current contents - google.protobuf.StringValue memo = 5; // If set, the new memo to be associated with the file (UTF-8 encoding max 100 bytes) + /** + * The ID of the file to update + */ + FileID fileID = 1; + + /** + * The new expiry time (ignored if not later than the current expiry) + */ + Timestamp expirationTime = 2; + + /** + * The new list of keys that can modify or delete the file + */ + KeyList keys = 3; + + /** + * The new contents that should overwrite the file's current contents + */ + bytes contents = 4; + + /** + * If set, the new memo to be associated with the file (UTF-8 encoding max 100 bytes) + */ + google.protobuf.StringValue memo = 5; } diff --git a/services/freeze.proto b/services/freeze.proto index d060acb1..e6c741c0 100644 --- a/services/freeze.proto +++ b/services/freeze.proto @@ -29,13 +29,44 @@ import "duration.proto"; import "timestamp.proto"; import "basic_types.proto"; -/* At consensus, sets the consensus time at which the platform should stop creating events and accepting transactions, and enter a maintenance window. */ +/** + * At consensus, sets the consensus time at which the platform should stop creating events and + * accepting transactions, and enter a maintenance window. + */ message FreezeTransactionBody { - int32 startHour = 1 [deprecated=true]; // The start hour (in UTC time), a value between 0 and 23 - int32 startMin = 2 [deprecated=true]; // The start minute (in UTC time), a value between 0 and 59 - int32 endHour = 3 [deprecated=true]; // The end hour (in UTC time), a value between 0 and 23 - int32 endMin = 4 [deprecated=true]; // The end minute (in UTC time), a value between 0 and 59 - FileID update_file = 5; // If set, the file whose contents should be used for a network software update during the maintenance window - bytes file_hash = 6; // If set, the expected hash of the contents of the update file (used to verify the update) - Timestamp start_time = 7; // The consensus time at which the maintenance window should begin + /** + * The start hour (in UTC time), a value between 0 and 23 + */ + int32 startHour = 1 [deprecated=true]; + + /** + * The start minute (in UTC time), a value between 0 and 59 + */ + int32 startMin = 2 [deprecated=true]; + + /** + * The end hour (in UTC time), a value between 0 and 23 + */ + int32 endHour = 3 [deprecated=true]; + + /** + * The end minute (in UTC time), a value between 0 and 59 + */ + int32 endMin = 4 [deprecated=true]; + + /** + * If set, the file whose contents should be used for a network software update during the + * maintenance window + */ + FileID update_file = 5; + + /** + * If set, the expected hash of the contents of the update file (used to verify the update) + */ + bytes file_hash = 6; + + /** + * The consensus time at which the maintenance window should begin + */ + Timestamp start_time = 7; } diff --git a/services/freeze_service.proto b/services/freeze_service.proto index a47fd9cb..c322444a 100644 --- a/services/freeze_service.proto +++ b/services/freeze_service.proto @@ -26,8 +26,13 @@ option java_package = "com.hederahashgraph.service.proto.java"; import "transaction_response.proto"; import "transaction.proto"; -/* The request and responses for freeze service. */ +/** + * The request and responses for freeze service. + */ service FreezeService { - - rpc freeze (Transaction) returns (TransactionResponse); // Freezes the nodes by submitting the transaction. The grpc server returns the TransactionResponse + /** + * Freezes the nodes by submitting the transaction. The grpc server returns the + * TransactionResponse + */ + rpc freeze (Transaction) returns (TransactionResponse); } diff --git a/services/get_by_key.proto b/services/get_by_key.proto index e0732c8d..93aee4f3 100644 --- a/services/get_by_key.proto +++ b/services/get_by_key.proto @@ -30,25 +30,64 @@ import "query_header.proto"; import "response_header.proto"; import "crypto_add_live_hash.proto"; -/* Get all accounts, claims, files, and smart contract instances whose associated keys include the given Key. The given Key must not be a contractID or a ThresholdKey. This is not yet implemented in the API, but will be in the future. */ +/** + * Get all accounts, claims, files, and smart contract instances whose associated keys include the + * given Key. The given Key must not be a contractID or a ThresholdKey. This is not yet implemented + * in the API, but will be in the future. + */ message GetByKeyQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - Key key = 2; // The key to search for. It must not contain a contractID nor a ThresholdSignature. + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The key to search for. It must not contain a contractID nor a ThresholdSignature. + */ + Key key = 2; } -/* the ID for a single entity (account, livehash, file, or smart contract instance) */ +/** + * the ID for a single entity (account, livehash, file, or smart contract instance) + */ message EntityID { oneof entity { - AccountID accountID = 1; // The Account ID for the cryptocurrency account - LiveHash liveHash = 2; // A uniquely identifying livehash of an acount - FileID fileID = 3; // The file ID of the file - ContractID contractID = 4; // The smart contract ID that identifies instance + /** + * The Account ID for the cryptocurrency account + */ + AccountID accountID = 1; + + /** + * A uniquely identifying livehash of an acount + */ + LiveHash liveHash = 2; + + /** + * The file ID of the file + */ + FileID fileID = 3; + + /** + * The smart contract ID that identifies instance + */ + ContractID contractID = 4; + } } -/* Response when the client sends the node GetByKeyQuery */ -message GetByKeyResponse { - ResponseHeader header = 1; //Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - repeated EntityID entities = 2; // The list of entities that include this public key in their associated Key list -} +/** + * Response when the client sends the node GetByKeyQuery + */ +message GetByKeyResponse { + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + /** + * The list of entities that include this public key in their associated Key list + */ + repeated EntityID entities = 2; +} diff --git a/services/get_by_solidity_id.proto b/services/get_by_solidity_id.proto index 55559dd8..a86382ce 100644 --- a/services/get_by_solidity_id.proto +++ b/services/get_by_solidity_id.proto @@ -29,18 +29,47 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* Get the IDs in the format used by transactions, given the ID in the format used by Solidity. If the Solidity ID is for a smart contract instance, then both the ContractID and associated AccountID will be returned. */ +/** + * Get the IDs in the format used by transactions, given the ID in the format used by Solidity. If + * the Solidity ID is for a smart contract instance, then both the ContractID and associated + * AccountID will be returned. + */ message GetBySolidityIDQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - string solidityID = 2; // The ID in the format used by Solidity + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The ID in the format used by Solidity + */ + string solidityID = 2; } -/* Response when the client sends the node GetBySolidityIDQuery */ +/** + * Response when the client sends the node GetBySolidityIDQuery + */ message GetBySolidityIDResponse { - ResponseHeader header = 1; // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - AccountID accountID = 2; // The Account ID for the cryptocurrency account - FileID fileID = 3; // The file Id for the file - ContractID contractID = 4; // A smart contract ID for the instance (if this is included, then the associated accountID will also be included) -} + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + + /** + * The Account ID for the cryptocurrency account + */ + AccountID accountID = 2; + /** + * The file Id for the file + */ + FileID fileID = 3; + /** + * A smart contract ID for the instance (if this is included, then the associated accountID will + * also be included) + */ + ContractID contractID = 4; +} diff --git a/services/network_get_version_info.proto b/services/network_get_version_info.proto index 1ef57d1f..3e7b9e86 100644 --- a/services/network_get_version_info.proto +++ b/services/network_get_version_info.proto @@ -29,14 +29,34 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* Get the deployed versions of Hedera Services and the HAPI proto in semantic version format */ +/** + * Get the deployed versions of Hedera Services and the HAPI proto in semantic version format + */ message NetworkGetVersionInfoQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; } -/* Response when the client sends the node NetworkGetVersionInfoQuery */ +/** + * Response when the client sends the node NetworkGetVersionInfoQuery + */ message NetworkGetVersionInfoResponse { - ResponseHeader header = 1; // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - SemanticVersion hapiProtoVersion = 2; // The Hedera API (HAPI) protobuf version recognized by the responding node. - SemanticVersion hederaServicesVersion = 3; // The version of the Hedera Services software deployed on the responding node. + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + + /** + * The Hedera API (HAPI) protobuf version recognized by the responding node. + */ + SemanticVersion hapiProtoVersion = 2; + + /** + * The version of the Hedera Services software deployed on the responding node. + */ + SemanticVersion hederaServicesVersion = 3; } diff --git a/services/network_service.proto b/services/network_service.proto index ee702bb0..7508dbae 100644 --- a/services/network_service.proto +++ b/services/network_service.proto @@ -29,8 +29,20 @@ import "response.proto"; import "transaction_response.proto"; import "transaction.proto"; -/* The requests and responses for different network services. */ +/** + * The requests and responses for different network services. + */ service NetworkService { - rpc getVersionInfo (Query) returns (Response); // Retrieves the active versions of Hedera Services and HAPI proto - rpc uncheckedSubmit (Transaction) returns (TransactionResponse); // Submits a "wrapped" transaction to the network, skipping its standard prechecks. (Note that the "wrapper" UncheckedSubmit transaction is still subject to normal prechecks, including an authorization requirement that its payer be either the treasury or system admin account.) + /** + * Retrieves the active versions of Hedera Services and HAPI proto + */ + rpc getVersionInfo (Query) returns (Response); + + /** + * Submits a "wrapped" transaction to the network, skipping its standard prechecks. (Note that + * the "wrapper" UncheckedSubmit transaction is still subject to normal prechecks, + * including an authorization requirement that its payer be either the treasury or system admin + * account.) + */ + rpc uncheckedSubmit (Transaction) returns (TransactionResponse); } diff --git a/services/query.proto b/services/query.proto index f081bebe..72108ed2 100644 --- a/services/query.proto +++ b/services/query.proto @@ -56,38 +56,131 @@ import "token_get_account_nft_infos.proto"; import "token_get_nft_info.proto"; import "token_get_nft_infos.proto"; -/* A single query, which is sent from the client to a node. This includes all possible queries. Each Query should not have more than 50 levels. */ +/** + * A single query, which is sent from the client to a node. This includes all possible queries. Each + * Query should not have more than 50 levels. + */ message Query { oneof query { - GetByKeyQuery getByKey = 1; // Get all entities associated with a given key - GetBySolidityIDQuery getBySolidityID = 2; // Get the IDs in the format used in transactions, given the format used in Solidity - ContractCallLocalQuery contractCallLocal = 3; // Call a function of a smart contract instance - ContractGetInfoQuery contractGetInfo = 4; // Get information about a smart contract instance - ContractGetBytecodeQuery contractGetBytecode = 5; // Get bytecode used by a smart contract instance - ContractGetRecordsQuery ContractGetRecords = 6; // Get Records of the contract instance - - CryptoGetAccountBalanceQuery cryptogetAccountBalance = 7; // Get the current balance in a cryptocurrency account - CryptoGetAccountRecordsQuery cryptoGetAccountRecords = 8; // Get all the records that currently exist for transactions involving an account - CryptoGetInfoQuery cryptoGetInfo = 9; // Get all information about an account - CryptoGetLiveHashQuery cryptoGetLiveHash = 10; // Get a single livehash from a single account, if present - CryptoGetStakersQuery cryptoGetProxyStakers = 11; // Get all the accounts that proxy stake to a given account, and how much they proxy stake (not yet implemented in the current API) - - FileGetContentsQuery fileGetContents = 12; // Get the contents of a file (the bytes stored in it) - FileGetInfoQuery fileGetInfo = 13; // Get information about a file, such as its expiration date - - TransactionGetReceiptQuery transactionGetReceipt = 14; // Get a receipt for a transaction (lasts 180 seconds) - TransactionGetRecordQuery transactionGetRecord = 15; // Get a record for a transaction - TransactionGetFastRecordQuery transactionGetFastRecord = 16; // Get a record for a transaction (lasts 180 seconds) - ConsensusGetTopicInfoQuery consensusGetTopicInfo = 50; // Get the parameters of and state of a consensus topic. - - NetworkGetVersionInfoQuery networkGetVersionInfo = 51; // Get the versions of the HAPI protobuf and Hedera Services software deployed on the responding node. - - TokenGetInfoQuery tokenGetInfo = 52; // Get all information about a token - - ScheduleGetInfoQuery scheduleGetInfo = 53; // Get all information about a scheduled entity - - TokenGetAccountNftInfosQuery tokenGetAccountNftInfos = 54; // Get a list of NFTs associated with the account - TokenGetNftInfoQuery tokenGetNftInfo = 55; // Get all information about a NFT - TokenGetNftInfosQuery tokenGetNftInfos = 56; // Get a list of NFTs for the token + /** + * Get all entities associated with a given key + */ + GetByKeyQuery getByKey = 1; + + /** + * Get the IDs in the format used in transactions, given the format used in Solidity + */ + GetBySolidityIDQuery getBySolidityID = 2; + + /** + * Call a function of a smart contract instance + */ + ContractCallLocalQuery contractCallLocal = 3; + + /** + * Get information about a smart contract instance + */ + ContractGetInfoQuery contractGetInfo = 4; + + /** + * Get bytecode used by a smart contract instance + */ + ContractGetBytecodeQuery contractGetBytecode = 5; + + /** + * Get Records of the contract instance + */ + ContractGetRecordsQuery ContractGetRecords = 6; + + + /** + * Get the current balance in a cryptocurrency account + */ + CryptoGetAccountBalanceQuery cryptogetAccountBalance = 7; + + /** + * Get all the records that currently exist for transactions involving an account + */ + CryptoGetAccountRecordsQuery cryptoGetAccountRecords = 8; + + /** + * Get all information about an account + */ + CryptoGetInfoQuery cryptoGetInfo = 9; + + /** + * Get a single livehash from a single account, if present + */ + CryptoGetLiveHashQuery cryptoGetLiveHash = 10; + + /** + * Get all the accounts that proxy stake to a given account, and how much they proxy stake + * (not yet implemented in the current API) + */ + CryptoGetStakersQuery cryptoGetProxyStakers = 11; + + /** + * Get the contents of a file (the bytes stored in it) + */ + FileGetContentsQuery fileGetContents = 12; + + /** + * Get information about a file, such as its expiration date + */ + FileGetInfoQuery fileGetInfo = 13; + + /** + * Get a receipt for a transaction (lasts 180 seconds) + */ + TransactionGetReceiptQuery transactionGetReceipt = 14; + + /** + * Get a record for a transaction + */ + TransactionGetRecordQuery transactionGetRecord = 15; + + /** + * Get a record for a transaction (lasts 180 seconds) + */ + TransactionGetFastRecordQuery transactionGetFastRecord = 16; + + /** + * Get the parameters of and state of a consensus topic. + */ + ConsensusGetTopicInfoQuery consensusGetTopicInfo = 50; + + /** + * Get the versions of the HAPI protobuf and Hedera Services software deployed on the + * responding node. + */ + NetworkGetVersionInfoQuery networkGetVersionInfo = 51; + + + /** + * Get all information about a token + */ + TokenGetInfoQuery tokenGetInfo = 52; + + + /** + * Get all information about a scheduled entity + */ + ScheduleGetInfoQuery scheduleGetInfo = 53; + + + /** + * Get a list of NFTs associated with the account + */ + TokenGetAccountNftInfosQuery tokenGetAccountNftInfos = 54; + + /** + * Get all information about a NFT + */ + TokenGetNftInfoQuery tokenGetNftInfo = 55; + + /** + * Get a list of NFTs for the token + */ + TokenGetNftInfosQuery tokenGetNftInfos = 56; } } diff --git a/services/query_header.proto b/services/query_header.proto index 2dbe5b57..849b1c07 100644 --- a/services/query_header.proto +++ b/services/query_header.proto @@ -27,24 +27,49 @@ option java_multiple_files = true; import "transaction.proto"; -/* -The client uses the ResponseType to indicate that it desires the node send just the answer, or both the answer and a state proof. It can also ask for just the cost and not the answer itself (allowing it to tailor the payment transaction accordingly). If the payment in the query fails the precheck, then the response may have some fields blank. The state proof is only available for some types of information. It is available for a Record, but not a receipt. It is available for the information in each kind of *GetInfo request. -*/ +/** + * The client uses the ResponseType to indicate that it desires the node send just the answer, or + * both the answer and a state proof. It can also ask for just the cost and not the answer itself + * (allowing it to tailor the payment transaction accordingly). If the payment in the query fails + * the precheck, then the response may have some fields blank. The state proof is only available for + * some types of information. It is available for a Record, but not a receipt. It is available for + * the information in each kind of *GetInfo request. + */ enum ResponseType { - // Response returns answer + /** + * Response returns answer + */ ANSWER_ONLY = 0; - // (NOT YET SUPPORTED) Response returns both answer and state proof + + /** + * (NOT YET SUPPORTED) Response returns both answer and state proof + */ ANSWER_STATE_PROOF = 1; - // Response returns the cost of answer + + /** + * Response returns the cost of answer + */ COST_ANSWER = 2; - // (NOT YET SUPPORTED) Response returns the total cost of answer and state proof + + /** + * (NOT YET SUPPORTED) Response returns the total cost of answer and state proof + */ COST_ANSWER_STATE_PROOF = 3; } -/* -Each query from the client to the node will contain the QueryHeader, which gives the requested response type, and includes a payment transaction that will compensate the node for responding to the query. The payment can be blank if the query is free. -*/ +/** + * Each query from the client to the node will contain the QueryHeader, which gives the requested + * response type, and includes a payment transaction that will compensate the node for responding to + * the query. The payment can be blank if the query is free. + */ message QueryHeader { - Transaction payment = 1; // A signed CryptoTransferTransaction to pay the node a fee for handling this query - ResponseType responseType = 2; // The requested response, asking for cost, state proof, both, or neither + /** + * A signed CryptoTransferTransaction to pay the node a fee for handling this query + */ + Transaction payment = 1; + + /** + * The requested response, asking for cost, state proof, both, or neither + */ + ResponseType responseType = 2; } diff --git a/services/response.proto b/services/response.proto index 3e613325..ea7eccdf 100644 --- a/services/response.proto +++ b/services/response.proto @@ -58,40 +58,125 @@ import "token_get_nft_infos.proto"; import "schedule_get_info.proto"; -/* A single response, which is returned from the node to the client, after the client sent the node a query. This includes all responses. */ +/** + * A single response, which is returned from the node to the client, after the client sent the node + * a query. This includes all responses. + */ message Response { oneof response { - GetByKeyResponse getByKey = 1; // Get all entities associated with a given key - GetBySolidityIDResponse getBySolidityID = 2; // Get the IDs in the format used in transactions, given the format used in Solidity - - ContractCallLocalResponse contractCallLocal = 3; // Response to call a function of a smart contract instance - ContractGetBytecodeResponse contractGetBytecodeResponse = 5; // Get the bytecode for a smart contract instance - ContractGetInfoResponse contractGetInfo = 4; // Get information about a smart contract instance - ContractGetRecordsResponse contractGetRecordsResponse = 6; //Get all existing records for a smart contract instance - - CryptoGetAccountBalanceResponse cryptogetAccountBalance = 7; // Get the current balance in a cryptocurrency account - CryptoGetAccountRecordsResponse cryptoGetAccountRecords = 8; // Get all the records that currently exist for transactions involving an account - CryptoGetInfoResponse cryptoGetInfo = 9; // Get all information about an account - CryptoGetLiveHashResponse cryptoGetLiveHash = 10; // Contains a livehash associated to an account - CryptoGetStakersResponse cryptoGetProxyStakers = 11; // Get all the accounts that proxy stake to a given account, and how much they proxy stake - - FileGetContentsResponse fileGetContents = 12; // Get the contents of a file (the bytes stored in it) - FileGetInfoResponse fileGetInfo = 13; // Get information about a file, such as its expiration date - - TransactionGetReceiptResponse transactionGetReceipt = 14; // Get a receipt for a transaction - TransactionGetRecordResponse transactionGetRecord = 15; // Get a record for a transaction - TransactionGetFastRecordResponse transactionGetFastRecord = 16; // Get a record for a transaction (lasts 180 seconds) - - ConsensusGetTopicInfoResponse consensusGetTopicInfo = 150; // Parameters of and state of a consensus topic.. - - NetworkGetVersionInfoResponse networkGetVersionInfo = 151; // Semantic versions of Hedera Services and HAPI proto - - TokenGetInfoResponse tokenGetInfo = 152; // Get all information about a token - - ScheduleGetInfoResponse scheduleGetInfo = 153; // Get all information about a schedule entity - - TokenGetAccountNftInfosResponse tokenGetAccountNftInfos = 154; // A list of the NFTs associated with the account - TokenGetNftInfoResponse tokenGetNftInfo = 155; // All information about an NFT - TokenGetNftInfosResponse tokenGetNftInfos = 156; // A list of the NFTs for the token + /** + * Get all entities associated with a given key + */ + GetByKeyResponse getByKey = 1; + + /** + * Get the IDs in the format used in transactions, given the format used in Solidity + */ + GetBySolidityIDResponse getBySolidityID = 2; + + /** + * Response to call a function of a smart contract instance + */ + ContractCallLocalResponse contractCallLocal = 3; + + /** + * Get the bytecode for a smart contract instance + */ + ContractGetBytecodeResponse contractGetBytecodeResponse = 5; + + /** + * Get information about a smart contract instance + */ + ContractGetInfoResponse contractGetInfo = 4; + + /** + * Get all existing records for a smart contract instance + */ + ContractGetRecordsResponse contractGetRecordsResponse = 6; + + /** + * Get the current balance in a cryptocurrency account + */ + CryptoGetAccountBalanceResponse cryptogetAccountBalance = 7; + + /** + * Get all the records that currently exist for transactions involving an account + */ + CryptoGetAccountRecordsResponse cryptoGetAccountRecords = 8; + + /** + * Get all information about an account + */ + CryptoGetInfoResponse cryptoGetInfo = 9; + + /** + * Contains a livehash associated to an account + */ + CryptoGetLiveHashResponse cryptoGetLiveHash = 10; + + /** + * Get all the accounts that proxy stake to a given account, and how much they proxy stake + */ + CryptoGetStakersResponse cryptoGetProxyStakers = 11; + + /** + * Get the contents of a file (the bytes stored in it) + */ + FileGetContentsResponse fileGetContents = 12; + + /** + * Get information about a file, such as its expiration date + */ + FileGetInfoResponse fileGetInfo = 13; + + /** + * Get a receipt for a transaction + */ + TransactionGetReceiptResponse transactionGetReceipt = 14; + + /** + * Get a record for a transaction + */ + TransactionGetRecordResponse transactionGetRecord = 15; + + /** + * Get a record for a transaction (lasts 180 seconds) + */ + TransactionGetFastRecordResponse transactionGetFastRecord = 16; + + /** + * Parameters of and state of a consensus topic.. + */ + ConsensusGetTopicInfoResponse consensusGetTopicInfo = 150; + + /** + * Semantic versions of Hedera Services and HAPI proto + */ + NetworkGetVersionInfoResponse networkGetVersionInfo = 151; + + /** + * Get all information about a token + */ + TokenGetInfoResponse tokenGetInfo = 152; + + /** + * Get all information about a schedule entity + */ + ScheduleGetInfoResponse scheduleGetInfo = 153; + + /** + * A list of the NFTs associated with the account + */ + TokenGetAccountNftInfosResponse tokenGetAccountNftInfos = 154; + + /** + * All information about an NFT + */ + TokenGetNftInfoResponse tokenGetNftInfo = 155; + + /** + * A list of the NFTs for the token + */ + TokenGetNftInfosResponse tokenGetNftInfos = 156; } } diff --git a/services/response_code.proto b/services/response_code.proto index d49e9a4a..0a6d3d20 100644 --- a/services/response_code.proto +++ b/services/response_code.proto @@ -25,152 +25,631 @@ package proto; option java_package = "com.hederahashgraph.api.proto.java"; option java_multiple_files = true; +/** + * UNDOCUMENTED + */ enum ResponseCodeEnum { - OK = 0; // The transaction passed the precheck validations. - INVALID_TRANSACTION = 1; // For any error not handled by specific error codes listed below. - PAYER_ACCOUNT_NOT_FOUND = 2; //Payer account does not exist. - INVALID_NODE_ACCOUNT = 3; //Node Account provided does not match the node account of the node the transaction was submitted to. - TRANSACTION_EXPIRED = 4; // Pre-Check error when TransactionValidStart + transactionValidDuration is less than current consensus time. - INVALID_TRANSACTION_START = 5; // Transaction start time is greater than current consensus time - INVALID_TRANSACTION_DURATION = 6; //valid transaction duration is a positive non zero number that does not exceed 120 seconds - INVALID_SIGNATURE = 7; // The transaction signature is not valid - MEMO_TOO_LONG = 8; //Transaction memo size exceeded 100 bytes - INSUFFICIENT_TX_FEE = 9; // The fee provided in the transaction is insufficient for this type of transaction - INSUFFICIENT_PAYER_BALANCE = 10; // The payer account has insufficient cryptocurrency to pay the transaction fee - DUPLICATE_TRANSACTION = 11; // This transaction ID is a duplicate of one that was submitted to this node or reached consensus in the last 180 seconds (receipt period) - BUSY = 12; //If API is throttled out - NOT_SUPPORTED = 13; //The API is not currently supported - - INVALID_FILE_ID = 14; //The file id is invalid or does not exist - INVALID_ACCOUNT_ID = 15; //The account id is invalid or does not exist - INVALID_CONTRACT_ID = 16; //The contract id is invalid or does not exist - INVALID_TRANSACTION_ID = 17; //Transaction id is not valid - RECEIPT_NOT_FOUND = 18; //Receipt for given transaction id does not exist - RECORD_NOT_FOUND = 19; //Record for given transaction id does not exist - INVALID_SOLIDITY_ID = 20; //The solidity id is invalid or entity with this solidity id does not exist - - - UNKNOWN = 21; // The responding node has submitted the transaction to the network. Its final status is still unknown. - SUCCESS = 22; // The transaction succeeded - FAIL_INVALID = 23; // There was a system error and the transaction failed because of invalid request parameters. - FAIL_FEE = 24; // There was a system error while performing fee calculation, reserved for future. - FAIL_BALANCE = 25; // There was a system error while performing balance checks, reserved for future. - - - KEY_REQUIRED = 26; //Key not provided in the transaction body - BAD_ENCODING = 27; //Unsupported algorithm/encoding used for keys in the transaction - INSUFFICIENT_ACCOUNT_BALANCE = 28; //When the account balance is not sufficient for the transfer - INVALID_SOLIDITY_ADDRESS = 29; //During an update transaction when the system is not able to find the Users Solidity address - - - INSUFFICIENT_GAS = 30; //Not enough gas was supplied to execute transaction - CONTRACT_SIZE_LIMIT_EXCEEDED = 31; //contract byte code size is over the limit - LOCAL_CALL_MODIFICATION_EXCEPTION = 32; //local execution (query) is requested for a function which changes state - CONTRACT_REVERT_EXECUTED = 33; //Contract REVERT OPCODE executed - CONTRACT_EXECUTION_EXCEPTION = 34; //For any contract execution related error not handled by specific error codes listed above. - INVALID_RECEIVING_NODE_ACCOUNT = 35; //In Query validation, account with +ve(amount) value should be Receiving node account, the receiver account should be only one account in the list - MISSING_QUERY_HEADER = 36; // Header is missing in Query request - - - ACCOUNT_UPDATE_FAILED = 37; // The update of the account failed - INVALID_KEY_ENCODING = 38; // Provided key encoding was not supported by the system - NULL_SOLIDITY_ADDRESS = 39; // null solidity address - - CONTRACT_UPDATE_FAILED = 40; // update of the contract failed - INVALID_QUERY_HEADER = 41; // the query header is invalid - - INVALID_FEE_SUBMITTED = 42; // Invalid fee submitted - INVALID_PAYER_SIGNATURE = 43; // Payer signature is invalid - - - KEY_NOT_PROVIDED = 44; // The keys were not provided in the request. - INVALID_EXPIRATION_TIME = 45; // Expiration time provided in the transaction was invalid. - NO_WACL_KEY = 46; //WriteAccess Control Keys are not provided for the file - FILE_CONTENT_EMPTY = 47; //The contents of file are provided as empty. - INVALID_ACCOUNT_AMOUNTS = 48; // The crypto transfer credit and debit do not sum equal to 0 - EMPTY_TRANSACTION_BODY = 49; // Transaction body provided is empty - INVALID_TRANSACTION_BODY = 50; // Invalid transaction body provided - - - INVALID_SIGNATURE_TYPE_MISMATCHING_KEY = 51; // the type of key (base ed25519 key, KeyList, or ThresholdKey) does not match the type of signature (base ed25519 signature, SignatureList, or ThresholdKeySignature) - INVALID_SIGNATURE_COUNT_MISMATCHING_KEY = 52; // the number of key (KeyList, or ThresholdKey) does not match that of signature (SignatureList, or ThresholdKeySignature). e.g. if a keyList has 3 base keys, then the corresponding signatureList should also have 3 base signatures. - - EMPTY_LIVE_HASH_BODY = 53; // the livehash body is empty - EMPTY_LIVE_HASH = 54; // the livehash data is missing - EMPTY_LIVE_HASH_KEYS = 55; // the keys for a livehash are missing - INVALID_LIVE_HASH_SIZE = 56; // the livehash data is not the output of a SHA-384 digest - - EMPTY_QUERY_BODY = 57; // the query body is empty - EMPTY_LIVE_HASH_QUERY = 58; // the crypto livehash query is empty - LIVE_HASH_NOT_FOUND = 59; // the livehash is not present - ACCOUNT_ID_DOES_NOT_EXIST = 60; // the account id passed has not yet been created. - LIVE_HASH_ALREADY_EXISTS = 61; // the livehash already exists for a given account - - - INVALID_FILE_WACL = 62; // File WACL keys are invalid - SERIALIZATION_FAILED = 63; // Serialization failure - TRANSACTION_OVERSIZE = 64; // The size of the Transaction is greater than transactionMaxBytes - TRANSACTION_TOO_MANY_LAYERS = 65; // The Transaction has more than 50 levels - CONTRACT_DELETED = 66; //Contract is marked as deleted - - PLATFORM_NOT_ACTIVE = 67; // the platform node is either disconnected or lagging behind. - KEY_PREFIX_MISMATCH = 68; // one public key matches more than one prefixes on the signature map - PLATFORM_TRANSACTION_NOT_CREATED = 69; // transaction not created by platform due to large backlog - INVALID_RENEWAL_PERIOD = 70; // auto renewal period is not a positive number of seconds - INVALID_PAYER_ACCOUNT_ID = 71; // the response code when a smart contract id is passed for a crypto API request - ACCOUNT_DELETED = 72; // the account has been marked as deleted - FILE_DELETED = 73; // the file has been marked as deleted - ACCOUNT_REPEATED_IN_ACCOUNT_AMOUNTS = 74; // same accounts repeated in the transfer account list - SETTING_NEGATIVE_ACCOUNT_BALANCE = 75; // attempting to set negative balance value for crypto account - OBTAINER_REQUIRED =76; // when deleting smart contract that has crypto balance either transfer account or transfer smart contract is required - OBTAINER_SAME_CONTRACT_ID =77; //when deleting smart contract that has crypto balance you can not use the same contract id as transferContractId as the one being deleted - OBTAINER_DOES_NOT_EXIST = 78; //transferAccountId or transferContractId specified for contract delete does not exist - MODIFYING_IMMUTABLE_CONTRACT = 79; //attempting to modify (update or delete a immutable smart contract, i.e. one created without a admin key) - FILE_SYSTEM_EXCEPTION = 80; //Unexpected exception thrown by file system functions - AUTORENEW_DURATION_NOT_IN_RANGE = 81; // the duration is not a subset of [MINIMUM_AUTORENEW_DURATION,MAXIMUM_AUTORENEW_DURATION] - ERROR_DECODING_BYTESTRING = 82; // Decoding the smart contract binary to a byte array failed. Check that the input is a valid hex string. - CONTRACT_FILE_EMPTY = 83; // File to create a smart contract was of length zero - CONTRACT_BYTECODE_EMPTY = 84; // Bytecode for smart contract is of length zero - INVALID_INITIAL_BALANCE=85; // Attempt to set negative initial balance - INVALID_RECEIVE_RECORD_THRESHOLD=86 [deprecated=true]; // [Deprecated]. attempt to set negative receive record threshold - INVALID_SEND_RECORD_THRESHOLD=87 [deprecated=true]; // [Deprecated]. attempt to set negative send record threshold - ACCOUNT_IS_NOT_GENESIS_ACCOUNT = 88; // Special Account Operations should be performed by only Genesis account, return this code if it is not Genesis Account - PAYER_ACCOUNT_UNAUTHORIZED = 89; // The fee payer account doesn't have permission to submit such Transaction - INVALID_FREEZE_TRANSACTION_BODY = 90; // FreezeTransactionBody is invalid - FREEZE_TRANSACTION_BODY_NOT_FOUND = 91; // FreezeTransactionBody does not exist - TRANSFER_LIST_SIZE_LIMIT_EXCEEDED = 92; //Exceeded the number of accounts (both from and to) allowed for crypto transfer list - RESULT_SIZE_LIMIT_EXCEEDED = 93; // Smart contract result size greater than specified maxResultSize - NOT_SPECIAL_ACCOUNT = 94; //The payer account is not a special account(account 0.0.55) - CONTRACT_NEGATIVE_GAS = 95; // Negative gas was offered in smart contract call - CONTRACT_NEGATIVE_VALUE = 96; // Negative value / initial balance was specified in a smart contract call / create - INVALID_FEE_FILE=97; // Failed to update fee file - INVALID_EXCHANGE_RATE_FILE=98; // Failed to update exchange rate file - INSUFFICIENT_LOCAL_CALL_GAS = 99; // Payment tendered for contract local call cannot cover both the fee and the gas - ENTITY_NOT_ALLOWED_TO_DELETE = 100; // Entities with Entity ID below 1000 are not allowed to be deleted - AUTHORIZATION_FAILED = 101; // Violating one of these rules: 1) treasury account can update all entities below 0.0.1000, 2) account 0.0.50 can update all entities from 0.0.51 - 0.0.80, 3) Network Function Master Account A/c 0.0.50 - Update all Network Function accounts & perform all the Network Functions listed below, 4) Network Function Accounts: i) A/c 0.0.55 - Update Address Book files (0.0.101/102), ii) A/c 0.0.56 - Update Fee schedule (0.0.111), iii) A/c 0.0.57 - Update Exchange Rate (0.0.112). - FILE_UPLOADED_PROTO_INVALID = 102; // Fee Schedule Proto uploaded but not valid (append or update is required) - FILE_UPLOADED_PROTO_NOT_SAVED_TO_DISK = 103; // Fee Schedule Proto uploaded but not valid (append or update is required) - FEE_SCHEDULE_FILE_PART_UPLOADED = 104; // Fee Schedule Proto File Part uploaded - EXCHANGE_RATE_CHANGE_LIMIT_EXCEEDED = 105; // The change on Exchange Rate exceeds Exchange_Rate_Allowed_Percentage - MAX_CONTRACT_STORAGE_EXCEEDED = 106; // Contract permanent storage exceeded the currently allowable limit - TRANSFER_ACCOUNT_SAME_AS_DELETE_ACCOUNT = 107; // Transfer Account should not be same as Account to be deleted + /** + * The transaction passed the precheck validations. + */ + OK = 0; + + /** + * For any error not handled by specific error codes listed below. + */ + INVALID_TRANSACTION = 1; + + /** + * Payer account does not exist. + */ + PAYER_ACCOUNT_NOT_FOUND = 2; + + /** + * Node Account provided does not match the node account of the node the transaction was submitted + * to. + */ + INVALID_NODE_ACCOUNT = 3; + + /** + * Pre-Check error when TransactionValidStart + transactionValidDuration is less than current + * consensus time. + */ + TRANSACTION_EXPIRED = 4; + + /** + * Transaction start time is greater than current consensus time + */ + INVALID_TRANSACTION_START = 5; + + /** + * valid transaction duration is a positive non zero number that does not exceed 120 seconds + */ + INVALID_TRANSACTION_DURATION = 6; + + /** + * The transaction signature is not valid + */ + INVALID_SIGNATURE = 7; + + /** + * Transaction memo size exceeded 100 bytes + */ + MEMO_TOO_LONG = 8; + + /** + * The fee provided in the transaction is insufficient for this type of transaction + */ + INSUFFICIENT_TX_FEE = 9; + + /** + * The payer account has insufficient cryptocurrency to pay the transaction fee + */ + INSUFFICIENT_PAYER_BALANCE = 10; + + /** + * This transaction ID is a duplicate of one that was submitted to this node or reached consensus + * in the last 180 seconds (receipt period) + */ + DUPLICATE_TRANSACTION = 11; + + /** + * If API is throttled out + */ + BUSY = 12; + + /** + * The API is not currently supported + */ + NOT_SUPPORTED = 13; + + /** + * The file id is invalid or does not exist + */ + INVALID_FILE_ID = 14; + + /** + * The account id is invalid or does not exist + */ + INVALID_ACCOUNT_ID = 15; + + /** + * The contract id is invalid or does not exist + */ + INVALID_CONTRACT_ID = 16; + + /** + * Transaction id is not valid + */ + INVALID_TRANSACTION_ID = 17; + + /** + * Receipt for given transaction id does not exist + */ + RECEIPT_NOT_FOUND = 18; + + /** + * Record for given transaction id does not exist + */ + RECORD_NOT_FOUND = 19; + + /** + * The solidity id is invalid or entity with this solidity id does not exist + */ + INVALID_SOLIDITY_ID = 20; + + /** + * The responding node has submitted the transaction to the network. Its final status is still + * unknown. + */ + UNKNOWN = 21; + + /** + * The transaction succeeded + */ + SUCCESS = 22; + + /** + * There was a system error and the transaction failed because of invalid request parameters. + */ + FAIL_INVALID = 23; + + /** + * There was a system error while performing fee calculation, reserved for future. + */ + FAIL_FEE = 24; + + /** + * There was a system error while performing balance checks, reserved for future. + */ + FAIL_BALANCE = 25; + + /** + * Key not provided in the transaction body + */ + KEY_REQUIRED = 26; + + /** + * Unsupported algorithm/encoding used for keys in the transaction + */ + BAD_ENCODING = 27; + + /** + * When the account balance is not sufficient for the transfer + */ + INSUFFICIENT_ACCOUNT_BALANCE = 28; + + /** + * During an update transaction when the system is not able to find the Users Solidity address + */ + INVALID_SOLIDITY_ADDRESS = 29; + + /** + * Not enough gas was supplied to execute transaction + */ + INSUFFICIENT_GAS = 30; + + /** + * contract byte code size is over the limit + */ + CONTRACT_SIZE_LIMIT_EXCEEDED = 31; + + /** + * local execution (query) is requested for a function which changes state + */ + LOCAL_CALL_MODIFICATION_EXCEPTION = 32; + + /** + * Contract REVERT OPCODE executed + */ + CONTRACT_REVERT_EXECUTED = 33; + + /** + * For any contract execution related error not handled by specific error codes listed above. + */ + CONTRACT_EXECUTION_EXCEPTION = 34; + + /** + * In Query validation, account with +ve(amount) value should be Receiving node account, the + * receiver account should be only one account in the list + */ + INVALID_RECEIVING_NODE_ACCOUNT = 35; + + /** + * Header is missing in Query request + */ + MISSING_QUERY_HEADER = 36; + + /** + * The update of the account failed + */ + ACCOUNT_UPDATE_FAILED = 37; + + /** + * Provided key encoding was not supported by the system + */ + INVALID_KEY_ENCODING = 38; + + /** + * null solidity address + */ + NULL_SOLIDITY_ADDRESS = 39; + + /** + * update of the contract failed + */ + CONTRACT_UPDATE_FAILED = 40; + + /** + * the query header is invalid + */ + INVALID_QUERY_HEADER = 41; + + /** + * Invalid fee submitted + */ + INVALID_FEE_SUBMITTED = 42; + + /** + * Payer signature is invalid + */ + INVALID_PAYER_SIGNATURE = 43; + + /** + * The keys were not provided in the request. + */ + KEY_NOT_PROVIDED = 44; + + /** + * Expiration time provided in the transaction was invalid. + */ + INVALID_EXPIRATION_TIME = 45; + + /** + * WriteAccess Control Keys are not provided for the file + */ + NO_WACL_KEY = 46; + + /** + * The contents of file are provided as empty. + */ + FILE_CONTENT_EMPTY = 47; + + /** + * The crypto transfer credit and debit do not sum equal to 0 + */ + INVALID_ACCOUNT_AMOUNTS = 48; + + /** + * Transaction body provided is empty + */ + EMPTY_TRANSACTION_BODY = 49; + + /** + * Invalid transaction body provided + */ + INVALID_TRANSACTION_BODY = 50; + + /** + * the type of key (base ed25519 key, KeyList, or ThresholdKey) does not match the type of + * signature (base ed25519 signature, SignatureList, or ThresholdKeySignature) + */ + INVALID_SIGNATURE_TYPE_MISMATCHING_KEY = 51; + + /** + * the number of key (KeyList, or ThresholdKey) does not match that of signature (SignatureList, + * or ThresholdKeySignature). e.g. if a keyList has 3 base keys, then the corresponding + * signatureList should also have 3 base signatures. + */ + INVALID_SIGNATURE_COUNT_MISMATCHING_KEY = 52; + + /** + * the livehash body is empty + */ + EMPTY_LIVE_HASH_BODY = 53; + + /** + * the livehash data is missing + */ + EMPTY_LIVE_HASH = 54; + + /** + * the keys for a livehash are missing + */ + EMPTY_LIVE_HASH_KEYS = 55; + + /** + * the livehash data is not the output of a SHA-384 digest + */ + INVALID_LIVE_HASH_SIZE = 56; + + /** + * the query body is empty + */ + EMPTY_QUERY_BODY = 57; + + /** + * the crypto livehash query is empty + */ + EMPTY_LIVE_HASH_QUERY = 58; + + /** + * the livehash is not present + */ + LIVE_HASH_NOT_FOUND = 59; + + /** + * the account id passed has not yet been created. + */ + ACCOUNT_ID_DOES_NOT_EXIST = 60; + + /** + * the livehash already exists for a given account + */ + LIVE_HASH_ALREADY_EXISTS = 61; + + /** + * File WACL keys are invalid + */ + INVALID_FILE_WACL = 62; + + /** + * Serialization failure + */ + SERIALIZATION_FAILED = 63; + + /** + * The size of the Transaction is greater than transactionMaxBytes + */ + TRANSACTION_OVERSIZE = 64; + + /** + * The Transaction has more than 50 levels + */ + TRANSACTION_TOO_MANY_LAYERS = 65; + + /** + * Contract is marked as deleted + */ + CONTRACT_DELETED = 66; + + /** + * the platform node is either disconnected or lagging behind. + */ + PLATFORM_NOT_ACTIVE = 67; + + /** + * one public key matches more than one prefixes on the signature map + */ + KEY_PREFIX_MISMATCH = 68; + + /** + * transaction not created by platform due to large backlog + */ + PLATFORM_TRANSACTION_NOT_CREATED = 69; + + /** + * auto renewal period is not a positive number of seconds + */ + INVALID_RENEWAL_PERIOD = 70; + + /** + * the response code when a smart contract id is passed for a crypto API request + */ + INVALID_PAYER_ACCOUNT_ID = 71; + + /** + * the account has been marked as deleted + */ + ACCOUNT_DELETED = 72; + + /** + * the file has been marked as deleted + */ + FILE_DELETED = 73; + + /** + * same accounts repeated in the transfer account list + */ + ACCOUNT_REPEATED_IN_ACCOUNT_AMOUNTS = 74; + + /** + * attempting to set negative balance value for crypto account + */ + SETTING_NEGATIVE_ACCOUNT_BALANCE = 75; + + /** + * when deleting smart contract that has crypto balance either transfer account or transfer smart + * contract is required + */ + OBTAINER_REQUIRED = 76; + + /** + * when deleting smart contract that has crypto balance you can not use the same contract id as + * transferContractId as the one being deleted + */ + OBTAINER_SAME_CONTRACT_ID = 77; + + /** + * transferAccountId or transferContractId specified for contract delete does not exist + */ + OBTAINER_DOES_NOT_EXIST = 78; + + /** + * attempting to modify (update or delete a immutable smart contract, i.e. one created without a + * admin key) + */ + MODIFYING_IMMUTABLE_CONTRACT = 79; + + /** + * Unexpected exception thrown by file system functions + */ + FILE_SYSTEM_EXCEPTION = 80; + + /** + * the duration is not a subset of [MINIMUM_AUTORENEW_DURATION,MAXIMUM_AUTORENEW_DURATION] + */ + AUTORENEW_DURATION_NOT_IN_RANGE = 81; + + /** + * Decoding the smart contract binary to a byte array failed. Check that the input is a valid hex + * string. + */ + ERROR_DECODING_BYTESTRING = 82; + + /** + * File to create a smart contract was of length zero + */ + CONTRACT_FILE_EMPTY = 83; + + /** + * Bytecode for smart contract is of length zero + */ + CONTRACT_BYTECODE_EMPTY = 84; + + /** + * Attempt to set negative initial balance + */ + INVALID_INITIAL_BALANCE = 85; + + /** + * [Deprecated]. attempt to set negative receive record threshold + */ + INVALID_RECEIVE_RECORD_THRESHOLD = 86 [deprecated=true]; + + /** + * [Deprecated]. attempt to set negative send record threshold + */ + INVALID_SEND_RECORD_THRESHOLD = 87 [deprecated=true]; + + /** + * Special Account Operations should be performed by only Genesis account, return this code if it + * is not Genesis Account + */ + ACCOUNT_IS_NOT_GENESIS_ACCOUNT = 88; + + /** + * The fee payer account doesn't have permission to submit such Transaction + */ + PAYER_ACCOUNT_UNAUTHORIZED = 89; + + /** + * FreezeTransactionBody is invalid + */ + INVALID_FREEZE_TRANSACTION_BODY = 90; + + /** + * FreezeTransactionBody does not exist + */ + FREEZE_TRANSACTION_BODY_NOT_FOUND = 91; + + /** + * Exceeded the number of accounts (both from and to) allowed for crypto transfer list + */ + TRANSFER_LIST_SIZE_LIMIT_EXCEEDED = 92; + + /** + * Smart contract result size greater than specified maxResultSize + */ + RESULT_SIZE_LIMIT_EXCEEDED = 93; + + /** + * The payer account is not a special account(account 0.0.55) + */ + NOT_SPECIAL_ACCOUNT = 94; + + /** + * Negative gas was offered in smart contract call + */ + CONTRACT_NEGATIVE_GAS = 95; + + /** + * Negative value / initial balance was specified in a smart contract call / create + */ + CONTRACT_NEGATIVE_VALUE = 96; + + /** + * Failed to update fee file + */ + INVALID_FEE_FILE = 97; + + /** + * Failed to update exchange rate file + */ + INVALID_EXCHANGE_RATE_FILE = 98; + + /** + * Payment tendered for contract local call cannot cover both the fee and the gas + */ + INSUFFICIENT_LOCAL_CALL_GAS = 99; + + /** + * Entities with Entity ID below 1000 are not allowed to be deleted + */ + ENTITY_NOT_ALLOWED_TO_DELETE = 100; + + /** + * Violating one of these rules: 1) treasury account can update all entities below 0.0.1000, 2) + * account 0.0.50 can update all entities from 0.0.51 - 0.0.80, 3) Network Function Master Account + * A/c 0.0.50 - Update all Network Function accounts & perform all the Network Functions listed + * below, 4) Network Function Accounts: i) A/c 0.0.55 - Update Address Book files (0.0.101/102), + * ii) A/c 0.0.56 - Update Fee schedule (0.0.111), iii) A/c 0.0.57 - Update Exchange Rate + * (0.0.112). + */ + AUTHORIZATION_FAILED = 101; + + /** + * Fee Schedule Proto uploaded but not valid (append or update is required) + */ + FILE_UPLOADED_PROTO_INVALID = 102; + + /** + * Fee Schedule Proto uploaded but not valid (append or update is required) + */ + FILE_UPLOADED_PROTO_NOT_SAVED_TO_DISK = 103; + + /** + * Fee Schedule Proto File Part uploaded + */ + FEE_SCHEDULE_FILE_PART_UPLOADED = 104; + + /** + * The change on Exchange Rate exceeds Exchange_Rate_Allowed_Percentage + */ + EXCHANGE_RATE_CHANGE_LIMIT_EXCEEDED = 105; + + /** + * Contract permanent storage exceeded the currently allowable limit + */ + MAX_CONTRACT_STORAGE_EXCEEDED = 106; + + /** + * Transfer Account should not be same as Account to be deleted + */ + TRANSFER_ACCOUNT_SAME_AS_DELETE_ACCOUNT = 107; + TOTAL_LEDGER_BALANCE_INVALID = 108; - EXPIRATION_REDUCTION_NOT_ALLOWED = 110; // The expiration date/time on a smart contract may not be reduced - MAX_GAS_LIMIT_EXCEEDED = 111; //Gas exceeded currently allowable gas limit per transaction - MAX_FILE_SIZE_EXCEEDED = 112; // File size exceeded the currently allowable limit - RECEIVER_SIG_REQUIRED = 113; // When a valid signature is not provided for operations on account with receiverSigRequired=true - - INVALID_TOPIC_ID = 150; // The Topic ID specified is not in the system. - INVALID_ADMIN_KEY = 155; // A provided admin key was invalid. - INVALID_SUBMIT_KEY = 156; // A provided submit key was invalid. - UNAUTHORIZED = 157; // An attempted operation was not authorized (ie - a deleteTopic for a topic with no adminKey). - INVALID_TOPIC_MESSAGE = 158; // A ConsensusService message is empty. - INVALID_AUTORENEW_ACCOUNT = 159; // The autoRenewAccount specified is not a valid, active account. - AUTORENEW_ACCOUNT_NOT_ALLOWED = 160; // An adminKey was not specified on the topic, so there must not be an autoRenewAccount. - // The topic has expired, was not automatically renewed, and is in a 7 day grace period before the topic will be - // deleted unrecoverably. This error response code will not be returned until autoRenew functionality is supported - // by HAPI. + /** + * The expiration date/time on a smart contract may not be reduced + */ + EXPIRATION_REDUCTION_NOT_ALLOWED = 110; + + /** + * Gas exceeded currently allowable gas limit per transaction + */ + MAX_GAS_LIMIT_EXCEEDED = 111; + + /** + * File size exceeded the currently allowable limit + */ + MAX_FILE_SIZE_EXCEEDED = 112; + + /** + * When a valid signature is not provided for operations on account with receiverSigRequired=true + */ + RECEIVER_SIG_REQUIRED = 113; + + /** + * The Topic ID specified is not in the system. + */ + INVALID_TOPIC_ID = 150; + + /** + * A provided admin key was invalid. + */ + INVALID_ADMIN_KEY = 155; + + /** + * A provided submit key was invalid. + */ + INVALID_SUBMIT_KEY = 156; + + /** + * An attempted operation was not authorized (ie - a deleteTopic for a topic with no adminKey). + */ + UNAUTHORIZED = 157; + + /** + * A ConsensusService message is empty. + */ + INVALID_TOPIC_MESSAGE = 158; + + /** + * The autoRenewAccount specified is not a valid, active account. + */ + INVALID_AUTORENEW_ACCOUNT = 159; + + /** + * An adminKey was not specified on the topic, so there must not be an autoRenewAccount. + */ + AUTORENEW_ACCOUNT_NOT_ALLOWED = 160; + + /** + * The topic has expired, was not automatically renewed, and is in a 7 day grace period before the + * topic will be deleted unrecoverably. This error response code will not be returned until + * autoRenew functionality is supported by HAPI. + */ TOPIC_EXPIRED = 162; + INVALID_CHUNK_NUMBER = 163; // chunk number must be from 1 to total (chunks) inclusive. INVALID_CHUNK_TRANSACTION_ID = 164; // For every chunk, the payer account that is part of initialTransactionID must match the Payer Account of this transaction. The entire initialTransactionID should match the transactionID of the first chunk, but this is not checked or enforced by Hedera except when the chunk number is 1. ACCOUNT_FROZEN_FOR_TOKEN = 165; // Account is frozen and cannot transact with the token @@ -210,67 +689,318 @@ enum ResponseCodeEnum { EMPTY_TOKEN_TRANSFER_BODY = 199; // TokenTransfersTransactionBody has no TokenTransferList EMPTY_TOKEN_TRANSFER_ACCOUNT_AMOUNTS = 200; // TokenTransfersTransactionBody has a TokenTransferList with no AccountAmounts - INVALID_SCHEDULE_ID = 201; // The Scheduled entity does not exist; or has now expired, been deleted, or been executed - SCHEDULE_IS_IMMUTABLE = 202; // The Scheduled entity cannot be modified. Admin key not set - INVALID_SCHEDULE_PAYER_ID = 203; // The provided Scheduled Payer does not exist - INVALID_SCHEDULE_ACCOUNT_ID = 204; // The Schedule Create Transaction TransactionID account does not exist - NO_NEW_VALID_SIGNATURES = 205; // The provided sig map did not contain any new valid signatures from required signers of the scheduled transaction - UNRESOLVABLE_REQUIRED_SIGNERS = 206; // The required signers for a scheduled transaction cannot be resolved, for example because they do not exist or have been deleted - SCHEDULED_TRANSACTION_NOT_IN_WHITELIST = 207; // Only whitelisted transaction types may be scheduled - SOME_SIGNATURES_WERE_INVALID = 208; // At least one of the signatures in the provided sig map did not represent a valid signature for any required signer - TRANSACTION_ID_FIELD_NOT_ALLOWED = 209; // The scheduled field in the TransactionID may not be set to true - IDENTICAL_SCHEDULE_ALREADY_CREATED = 210; // A schedule already exists with the same identifying fields of an attempted ScheduleCreate (that is, all fields other than scheduledPayerAccountID) - INVALID_ZERO_BYTE_IN_STRING = 211; // A string field in the transaction has a UTF-8 encoding with the prohibited zero byte - SCHEDULE_ALREADY_DELETED = 212; // A schedule being signed or deleted has already been deleted - SCHEDULE_ALREADY_EXECUTED = 213; // A schedule being signed or deleted has already been executed - MESSAGE_SIZE_TOO_LARGE = 214; // ConsensusSubmitMessage request's message size is larger than allowed. - OPERATION_REPEATED_IN_BUCKET_GROUPS = 215; // An operation was assigned to more than one throttle group in a given bucket - BUCKET_CAPACITY_OVERFLOW = 216; // The capacity needed to satisfy all opsPerSec groups in a bucket overflowed a signed 8-byte integral type - NODE_CAPACITY_NOT_SUFFICIENT_FOR_OPERATION = 217; // Given the network size in the address book, the node-level capacity for an operation would never be enough to accept a single request; usually means a bucket burstPeriod should be increased - BUCKET_HAS_NO_THROTTLE_GROUPS = 218; // A bucket was defined without any throttle groups - THROTTLE_GROUP_HAS_ZERO_OPS_PER_SEC = 219; // A throttle group was granted zero opsPerSec - SUCCESS_BUT_MISSING_EXPECTED_OPERATION = 220; // The throttle definitions file was updated, but some supported operations were not assigned a bucket - UNPARSEABLE_THROTTLE_DEFINITIONS = 221; // The new contents for the throttle definitions system file were not valid protobuf - INVALID_THROTTLE_DEFINITIONS = 222; // The new throttle definitions system file were invalid, and no more specific error could be divined - ACCOUNT_EXPIRED_AND_PENDING_REMOVAL = 223; // The transaction references an account which has passed its expiration without renewal funds available, and currently remains in the ledger only because of the grace period given to expired entities - INVALID_TOKEN_MAX_SUPPLY = 224; // Invalid token max supply - INVALID_TOKEN_NFT_SERIAL_NUMBER = 225; // Invalid token nft serial number - INVALID_NFT_ID = 226; // Invalid nft id - METADATA_TOO_LONG = 227; // Nft metadata is too long - BATCH_SIZE_LIMIT_EXCEEDED = 228; // Repeated operations count exceeds the limit - INVALID_QUERY_RANGE = 229; // The range of data to be gathered is out of the set boundaries - FRACTION_DIVIDES_BY_ZERO = 230; // A custom fractional fee set a denominator of zero - INSUFFICIENT_PAYER_BALANCE_FOR_CUSTOM_FEE = 231 [deprecated = true]; // The transaction payer could not afford a custom fee - CUSTOM_FEES_LIST_TOO_LONG = 232; // More than 10 custom fees were specified - INVALID_CUSTOM_FEE_COLLECTOR = 233; // Any of the feeCollector accounts for customFees is invalid - INVALID_TOKEN_ID_IN_CUSTOM_FEES = 234; // Any of the token Ids in customFees is invalid - TOKEN_NOT_ASSOCIATED_TO_FEE_COLLECTOR = 235; // Any of the token Ids in customFees are not associated to feeCollector - TOKEN_MAX_SUPPLY_REACHED = 236; // A token cannot have more units minted due to its configured supply ceiling - SENDER_DOES_NOT_OWN_NFT_SERIAL_NO = 237; // The transaction attempted to move an NFT serial number from an account other than its owner - CUSTOM_FEE_NOT_FULLY_SPECIFIED = 238; // A custom fee schedule entry did not specify either a fixed or fractional fee - CUSTOM_FEE_MUST_BE_POSITIVE = 239; // Only positive fees may be assessed at this time - TOKEN_HAS_NO_FEE_SCHEDULE_KEY = 240; // Fee schedule key is not set on token - CUSTOM_FEE_OUTSIDE_NUMERIC_RANGE = 241; // A fractional custom fee exceeded the range of a 64-bit signed integer - ROYALTY_FRACTION_CANNOT_EXCEED_ONE = 242; // A royalty cannot exceed the total fungible value exchanged for an NFT - FRACTIONAL_FEE_MAX_AMOUNT_LESS_THAN_MIN_AMOUNT = 243; // Each fractional custom fee must have its maximum_amount, if specified, at least its minimum_amount - CUSTOM_SCHEDULE_ALREADY_HAS_NO_FEES = 244; // A fee schedule update tried to clear the custom fees from a token whose fee schedule was already empty - CUSTOM_FEE_DENOMINATION_MUST_BE_FUNGIBLE_COMMON = 245; // Only tokens of type FUNGIBLE_COMMON can be used to as fee schedule denominations - CUSTOM_FRACTIONAL_FEE_ONLY_ALLOWED_FOR_FUNGIBLE_COMMON = 246; // Only tokens of type FUNGIBLE_COMMON can have fractional fees - INVALID_CUSTOM_FEE_SCHEDULE_KEY = 247; // The provided custom fee schedule key was invalid - INVALID_TOKEN_MINT_METADATA = 248; // The requested token mint metadata was invalid - INVALID_TOKEN_BURN_METADATA = 249; // The requested token burn metadata was invalid - CURRENT_TREASURY_STILL_OWNS_NFTS = 250; // The treasury for a unique token cannot be changed until it owns no NFTs - ACCOUNT_STILL_OWNS_NFTS = 251; // An account cannot be dissociated from a unique token if it owns NFTs for the token - TREASURY_MUST_OWN_BURNED_NFT = 252; // A NFT can only be burned when owned by the unique token's treasury - ACCOUNT_DOES_NOT_OWN_WIPED_NFT = 253; // An account did not own the NFT to be wiped - ACCOUNT_AMOUNT_TRANSFERS_ONLY_ALLOWED_FOR_FUNGIBLE_COMMON = 254; // An AccountAmount token transfers list referenced a token type other than FUNGIBLE_COMMON - MAX_NFTS_IN_PRICE_REGIME_HAVE_BEEN_MINTED = 255; // All the NFTs allowed in the current price regime have already been minted - PAYER_ACCOUNT_DELETED = 256; // The payer account has been marked as deleted - CUSTOM_FEE_CHARGING_EXCEEDED_MAX_RECURSION_DEPTH = 257; // The reference chain of custom fees for a transferred token exceeded the maximum length of 2 - CUSTOM_FEE_CHARGING_EXCEEDED_MAX_ACCOUNT_AMOUNTS = 258; // More than 20 balance adjustments were to satisfy a CryptoTransfer and its implied custom fee payments - INSUFFICIENT_SENDER_ACCOUNT_BALANCE_FOR_CUSTOM_FEE = 259; // The sender account in the token transfer transaction could not afford a custom fee - SERIAL_NUMBER_LIMIT_REACHED = 260; // Currently no more than 4,294,967,295 NFTs may be minted for a given unique token type - CUSTOM_ROYALTY_FEE_ONLY_ALLOWED_FOR_NON_FUNGIBLE_UNIQUE = 261; // Only tokens of type NON_FUNGIBLE_UNIQUE can have royalty fees - NO_REMAINING_AUTO_ASSOCIATIONS = 262; // The account has reached the limit on the automatic associations count. - EXISTING_AUTOMATIC_ASSOCIATIONS_EXCEED_GIVEN_LIMIT = 263; // Already existing automatic associations are more than the new maximum automatic associations. + /** + * The Scheduled entity does not exist; or has now expired, been deleted, or been executed + */ + INVALID_SCHEDULE_ID = 201; + + /** + * The Scheduled entity cannot be modified. Admin key not set + */ + SCHEDULE_IS_IMMUTABLE = 202; + + /** + * The provided Scheduled Payer does not exist + */ + INVALID_SCHEDULE_PAYER_ID = 203; + + /** + * The Schedule Create Transaction TransactionID account does not exist + */ + INVALID_SCHEDULE_ACCOUNT_ID = 204; + + /** + * The provided sig map did not contain any new valid signatures from required signers of the scheduled transaction + */ + NO_NEW_VALID_SIGNATURES = 205; + + /** + * The required signers for a scheduled transaction cannot be resolved, for example because they do not exist or have been deleted + */ + UNRESOLVABLE_REQUIRED_SIGNERS = 206; + + /** + * Only whitelisted transaction types may be scheduled + */ + SCHEDULED_TRANSACTION_NOT_IN_WHITELIST = 207; + + /** + * At least one of the signatures in the provided sig map did not represent a valid signature for any required signer + */ + SOME_SIGNATURES_WERE_INVALID = 208; + + /** + * The scheduled field in the TransactionID may not be set to true + */ + TRANSACTION_ID_FIELD_NOT_ALLOWED = 209; + + /** + * A schedule already exists with the same identifying fields of an attempted ScheduleCreate (that is, all fields other than scheduledPayerAccountID) + */ + IDENTICAL_SCHEDULE_ALREADY_CREATED = 210; + + /** + * A string field in the transaction has a UTF-8 encoding with the prohibited zero byte + */ + INVALID_ZERO_BYTE_IN_STRING = 211; + + /** + * A schedule being signed or deleted has already been deleted + */ + SCHEDULE_ALREADY_DELETED = 212; + + /** + * A schedule being signed or deleted has already been executed + */ + SCHEDULE_ALREADY_EXECUTED = 213; + + /** + * ConsensusSubmitMessage request's message size is larger than allowed. + */ + MESSAGE_SIZE_TOO_LARGE = 214; + + /** + * An operation was assigned to more than one throttle group in a given bucket + */ + OPERATION_REPEATED_IN_BUCKET_GROUPS = 215; + + /** + * The capacity needed to satisfy all opsPerSec groups in a bucket overflowed a signed 8-byte integral type + */ + BUCKET_CAPACITY_OVERFLOW = 216; + + /** + * Given the network size in the address book, the node-level capacity for an operation would never be enough to accept a single request; usually means a bucket burstPeriod should be increased + */ + NODE_CAPACITY_NOT_SUFFICIENT_FOR_OPERATION = 217; + + /** + * A bucket was defined without any throttle groups + */ + BUCKET_HAS_NO_THROTTLE_GROUPS = 218; + + /** + * A throttle group was granted zero opsPerSec + */ + THROTTLE_GROUP_HAS_ZERO_OPS_PER_SEC = 219; + + /** + * The throttle definitions file was updated, but some supported operations were not assigned a bucket + */ + SUCCESS_BUT_MISSING_EXPECTED_OPERATION = 220; + + /** + * The new contents for the throttle definitions system file were not valid protobuf + */ + UNPARSEABLE_THROTTLE_DEFINITIONS = 221; + + /** + * The new throttle definitions system file were invalid, and no more specific error could be divined + */ + INVALID_THROTTLE_DEFINITIONS = 222; + + /** + * The transaction references an account which has passed its expiration without renewal funds available, and currently remains in the ledger only because of the grace period given to expired entities + */ + ACCOUNT_EXPIRED_AND_PENDING_REMOVAL = 223; + + /** + * Invalid token max supply + */ + INVALID_TOKEN_MAX_SUPPLY = 224; + + /** + * Invalid token nft serial number + */ + INVALID_TOKEN_NFT_SERIAL_NUMBER = 225; + + /** + * Invalid nft id + */ + INVALID_NFT_ID = 226; + + /** + * Nft metadata is too long + */ + METADATA_TOO_LONG = 227; + + /** + * Repeated operations count exceeds the limit + */ + BATCH_SIZE_LIMIT_EXCEEDED = 228; + + /** + * The range of data to be gathered is out of the set boundaries + */ + INVALID_QUERY_RANGE = 229; + + /** + * A custom fractional fee set a denominator of zero + */ + FRACTION_DIVIDES_BY_ZERO = 230; + + /** + * The transaction payer could not afford a custom fee + */ + INSUFFICIENT_PAYER_BALANCE_FOR_CUSTOM_FEE = 231 [deprecated = true]; + + /** + * More than 10 custom fees were specified + */ + CUSTOM_FEES_LIST_TOO_LONG = 232; + + /** + * Any of the feeCollector accounts for customFees is invalid + */ + INVALID_CUSTOM_FEE_COLLECTOR = 233; + + /** + * Any of the token Ids in customFees is invalid + */ + INVALID_TOKEN_ID_IN_CUSTOM_FEES = 234; + + /** + * Any of the token Ids in customFees are not associated to feeCollector + */ + TOKEN_NOT_ASSOCIATED_TO_FEE_COLLECTOR = 235; + + /** + * A token cannot have more units minted due to its configured supply ceiling + */ + TOKEN_MAX_SUPPLY_REACHED = 236; + + /** + * The transaction attempted to move an NFT serial number from an account other than its owner + */ + SENDER_DOES_NOT_OWN_NFT_SERIAL_NO = 237; + + /** + * A custom fee schedule entry did not specify either a fixed or fractional fee + */ + CUSTOM_FEE_NOT_FULLY_SPECIFIED = 238; + + /** + * Only positive fees may be assessed at this time + */ + CUSTOM_FEE_MUST_BE_POSITIVE = 239; + + /** + * Fee schedule key is not set on token + */ + TOKEN_HAS_NO_FEE_SCHEDULE_KEY = 240; + + /** + * A fractional custom fee exceeded the range of a 64-bit signed integer + */ + CUSTOM_FEE_OUTSIDE_NUMERIC_RANGE = 241; + + /** + * A royalty cannot exceed the total fungible value exchanged for an NFT + */ + ROYALTY_FRACTION_CANNOT_EXCEED_ONE = 242; + + /** + * Each fractional custom fee must have its maximum_amount, if specified, at least its minimum_amount + */ + FRACTIONAL_FEE_MAX_AMOUNT_LESS_THAN_MIN_AMOUNT = 243; + + /** + * A fee schedule update tried to clear the custom fees from a token whose fee schedule was already empty + */ + CUSTOM_SCHEDULE_ALREADY_HAS_NO_FEES = 244; + + /** + * Only tokens of type FUNGIBLE_COMMON can be used to as fee schedule denominations + */ + CUSTOM_FEE_DENOMINATION_MUST_BE_FUNGIBLE_COMMON = 245; + + /** + * Only tokens of type FUNGIBLE_COMMON can have fractional fees + */ + CUSTOM_FRACTIONAL_FEE_ONLY_ALLOWED_FOR_FUNGIBLE_COMMON = 246; + + /** + * The provided custom fee schedule key was invalid + */ + INVALID_CUSTOM_FEE_SCHEDULE_KEY = 247; + + /** + * The requested token mint metadata was invalid + */ + INVALID_TOKEN_MINT_METADATA = 248; + + /** + * The requested token burn metadata was invalid + */ + INVALID_TOKEN_BURN_METADATA = 249; + + /** + * The treasury for a unique token cannot be changed until it owns no NFTs + */ + CURRENT_TREASURY_STILL_OWNS_NFTS = 250; + + /** + * An account cannot be dissociated from a unique token if it owns NFTs for the token + */ + ACCOUNT_STILL_OWNS_NFTS = 251; + + /** + * A NFT can only be burned when owned by the unique token's treasury + */ + TREASURY_MUST_OWN_BURNED_NFT = 252; + + /** + * An account did not own the NFT to be wiped + */ + ACCOUNT_DOES_NOT_OWN_WIPED_NFT = 253; + + /** + * An AccountAmount token transfers list referenced a token type other than FUNGIBLE_COMMON + */ + ACCOUNT_AMOUNT_TRANSFERS_ONLY_ALLOWED_FOR_FUNGIBLE_COMMON = 254; + + /** + * All the NFTs allowed in the current price regime have already been minted + */ + MAX_NFTS_IN_PRICE_REGIME_HAVE_BEEN_MINTED = 255; + + /** + * The payer account has been marked as deleted + */ + PAYER_ACCOUNT_DELETED = 256; + + /** + * The reference chain of custom fees for a transferred token exceeded the maximum length of 2 + */ + CUSTOM_FEE_CHARGING_EXCEEDED_MAX_RECURSION_DEPTH = 257; + + /** + * More than 20 balance adjustments were to satisfy a CryptoTransfer and its implied custom fee payments + */ + CUSTOM_FEE_CHARGING_EXCEEDED_MAX_ACCOUNT_AMOUNTS = 258; + + /** + * The sender account in the token transfer transaction could not afford a custom fee + */ + INSUFFICIENT_SENDER_ACCOUNT_BALANCE_FOR_CUSTOM_FEE = 259; + + /** + * Currently no more than 4,294,967,295 NFTs may be minted for a given unique token type + */ + SERIAL_NUMBER_LIMIT_REACHED = 260; + + /** + * Only tokens of type NON_FUNGIBLE_UNIQUE can have royalty fees + */ + CUSTOM_ROYALTY_FEE_ONLY_ALLOWED_FOR_NON_FUNGIBLE_UNIQUE = 261; + + /** + * The account has reached the limit on the automatic associations count. + */ + NO_REMAINING_AUTO_ASSOCIATIONS = 262; + + /** + * Already existing automatic associations are more than the new maximum automatic associations. + */ + EXISTING_AUTOMATIC_ASSOCIATIONS_EXCEED_GIVEN_LIMIT = 263; } diff --git a/services/response_header.proto b/services/response_header.proto index 91c063ef..806f7264 100644 --- a/services/response_header.proto +++ b/services/response_header.proto @@ -29,10 +29,31 @@ import "transaction_response.proto"; import "query_header.proto"; import "response_code.proto"; -/* Every query receives a response containing the QueryResponseHeader. Either or both of the cost and stateProof fields may be blank, if the responseType didn't ask for the cost or stateProof. */ +/** + * Every query receives a response containing the QueryResponseHeader. Either or both of the cost + * and stateProof fields may be blank, if the responseType didn't ask for the cost or stateProof. + */ message ResponseHeader { - ResponseCodeEnum nodeTransactionPrecheckCode = 1; // Result of fee transaction precheck, saying it passed, or why it failed - ResponseType responseType = 2; // The requested response is repeated back here, for convenience - uint64 cost = 3; // The fee that would be charged to get the requested information (if a cost was requested). Note: This cost only includes the query fee and does not include the transfer fee(which is required to execute the transfer transaction to debit the payer account and credit the node account with query fee) - bytes stateProof = 4; // The state proof for this information (if a state proof was requested, and is available) + /** + * Result of fee transaction precheck, saying it passed, or why it failed + */ + ResponseCodeEnum nodeTransactionPrecheckCode = 1; + + /** + * The requested response is repeated back here, for convenience + */ + ResponseType responseType = 2; + + /** + * The fee that would be charged to get the requested information (if a cost was requested). + * Note: This cost only includes the query fee and does not include the transfer fee(which is + * required to execute the transfer transaction to debit the payer account and credit the node + * account with query fee) + */ + uint64 cost = 3; + + /** + * The state proof for this information (if a state proof was requested, and is available) + */ + bytes stateProof = 4; } diff --git a/services/schedulable_transaction_body.proto b/services/schedulable_transaction_body.proto index 4c45328d..bdb8a829 100644 --- a/services/schedulable_transaction_body.proto +++ b/services/schedulable_transaction_body.proto @@ -65,50 +65,183 @@ import "token_dissociate.proto"; import "schedule_delete.proto"; -/* A schedulable transaction. Note that the global/dynamic system property -scheduling.whitelist controls which transaction types may be scheduled. -In Hedera Services 0.13.0, it will include only CryptoTransfer and -ConsensusSubmitMessage functions. */ +/** + * A schedulable transaction. Note that the global/dynamic system property + * scheduling.whitelist controls which transaction types may be scheduled. In Hedera + * Services 0.13.0, it will include only CryptoTransfer and ConsensusSubmitMessage + * functions. + */ message SchedulableTransactionBody { - uint64 transactionFee = 1; // The maximum transaction fee the client is willing to pay - string memo = 2; // A memo to include the execution record; the UTF-8 encoding may be up to 100 bytes and must not include the zero byte + /** + * The maximum transaction fee the client is willing to pay + */ + uint64 transactionFee = 1; + + /** + * A memo to include the execution record; the UTF-8 encoding may be up to 100 bytes and must not + * include the zero byte + */ + string memo = 2; + oneof data { - ContractCallTransactionBody contractCall = 3; // Calls a function of a contract instance - ContractCreateTransactionBody contractCreateInstance = 4; // Creates a contract instance - ContractUpdateTransactionBody contractUpdateInstance = 5; // Updates a contract - ContractDeleteTransactionBody contractDeleteInstance = 6; //Delete contract and transfer remaining balance into specified account - - CryptoCreateTransactionBody cryptoCreateAccount = 7; // Create a new cryptocurrency account - CryptoDeleteTransactionBody cryptoDelete = 8; // Delete a cryptocurrency account (mark as deleted, and transfer hbars out) - CryptoTransferTransactionBody cryptoTransfer = 9; // Transfer amount between accounts - CryptoUpdateTransactionBody cryptoUpdateAccount = 10; // Modify information such as the expiration date for an account - - FileAppendTransactionBody fileAppend = 11; // Add bytes to the end of the contents of a file - FileCreateTransactionBody fileCreate = 12; // Create a new file - FileDeleteTransactionBody fileDelete = 13; // Delete a file (remove contents and mark as deleted until it expires) - FileUpdateTransactionBody fileUpdate = 14; // Modify information such as the expiration date for a file - SystemDeleteTransactionBody systemDelete = 15; // Hedera administrative deletion of a file or smart contract - SystemUndeleteTransactionBody systemUndelete = 16; //To undelete an entity deleted by SystemDelete - FreezeTransactionBody freeze = 17; // Freeze the nodes - - ConsensusCreateTopicTransactionBody consensusCreateTopic = 18; // Creates a topic - ConsensusUpdateTopicTransactionBody consensusUpdateTopic = 19; // Updates a topic - ConsensusDeleteTopicTransactionBody consensusDeleteTopic = 20; // Deletes a topic - ConsensusSubmitMessageTransactionBody consensusSubmitMessage = 21; // Submits message to a topic - - TokenCreateTransactionBody tokenCreation = 22; // Creates a token instance - TokenFreezeAccountTransactionBody tokenFreeze = 23; // Freezes account not to be able to transact with a token - TokenUnfreezeAccountTransactionBody tokenUnfreeze = 24; // Unfreezes account for a token - TokenGrantKycTransactionBody tokenGrantKyc = 25; // Grants KYC to an account for a token - TokenRevokeKycTransactionBody tokenRevokeKyc = 26; // Revokes KYC of an account for a token - TokenDeleteTransactionBody tokenDeletion = 27; // Deletes a token instance - TokenUpdateTransactionBody tokenUpdate = 28; // Updates a token instance - TokenMintTransactionBody tokenMint = 29; // Mints new tokens to a token's treasury account - TokenBurnTransactionBody tokenBurn = 30; // Burns tokens from a token's treasury account - TokenWipeAccountTransactionBody tokenWipe = 31; // Wipes amount of tokens from an account - TokenAssociateTransactionBody tokenAssociate = 32; // Associate tokens to an account - TokenDissociateTransactionBody tokenDissociate = 33; // Dissociate tokens from an account - - ScheduleDeleteTransactionBody scheduleDelete = 34; // Marks a schedule in the network's action queue as deleted, preventing it from executing + /** + * Calls a function of a contract instance + */ + ContractCallTransactionBody contractCall = 3; + + /** + * Creates a contract instance + */ + ContractCreateTransactionBody contractCreateInstance = 4; + + /** + * Updates a contract + */ + ContractUpdateTransactionBody contractUpdateInstance = 5; + + /** + * Delete contract and transfer remaining balance into specified account + */ + ContractDeleteTransactionBody contractDeleteInstance = 6; + + /** + * Create a new cryptocurrency account + */ + CryptoCreateTransactionBody cryptoCreateAccount = 7; + + /** + * Delete a cryptocurrency account (mark as deleted, and transfer hbars out) + */ + CryptoDeleteTransactionBody cryptoDelete = 8; + + /** + * Transfer amount between accounts + */ + CryptoTransferTransactionBody cryptoTransfer = 9; + + /** + * Modify information such as the expiration date for an account + */ + CryptoUpdateTransactionBody cryptoUpdateAccount = 10; + + /** + * Add bytes to the end of the contents of a file + */ + FileAppendTransactionBody fileAppend = 11; + + /** + * Create a new file + */ + FileCreateTransactionBody fileCreate = 12; + + /** + * Delete a file (remove contents and mark as deleted until it expires) + */ + FileDeleteTransactionBody fileDelete = 13; + + /** + * Modify information such as the expiration date for a file + */ + FileUpdateTransactionBody fileUpdate = 14; + + /** + * Hedera administrative deletion of a file or smart contract + */ + SystemDeleteTransactionBody systemDelete = 15; + + /** + * To undelete an entity deleted by SystemDelete + */ + SystemUndeleteTransactionBody systemUndelete = 16; + + /** + * Freeze the nodes + */ + FreezeTransactionBody freeze = 17; + + /** + * Creates a topic + */ + ConsensusCreateTopicTransactionBody consensusCreateTopic = 18; + + /** + * Updates a topic + */ + ConsensusUpdateTopicTransactionBody consensusUpdateTopic = 19; + + /** + * Deletes a topic + */ + ConsensusDeleteTopicTransactionBody consensusDeleteTopic = 20; + + /** + * Submits message to a topic + */ + ConsensusSubmitMessageTransactionBody consensusSubmitMessage = 21; + + /** + * Creates a token instance + */ + TokenCreateTransactionBody tokenCreation = 22; + + /** + * Freezes account not to be able to transact with a token + */ + TokenFreezeAccountTransactionBody tokenFreeze = 23; + + /** + * Unfreezes account for a token + */ + TokenUnfreezeAccountTransactionBody tokenUnfreeze = 24; + + /** + * Grants KYC to an account for a token + */ + TokenGrantKycTransactionBody tokenGrantKyc = 25; + + /** + * Revokes KYC of an account for a token + */ + TokenRevokeKycTransactionBody tokenRevokeKyc = 26; + + /** + * Deletes a token instance + */ + TokenDeleteTransactionBody tokenDeletion = 27; + + /** + * Updates a token instance + */ + TokenUpdateTransactionBody tokenUpdate = 28; + + /** + * Mints new tokens to a token's treasury account + */ + TokenMintTransactionBody tokenMint = 29; + + /** + * Burns tokens from a token's treasury account + */ + TokenBurnTransactionBody tokenBurn = 30; + + /** + * Wipes amount of tokens from an account + */ + TokenWipeAccountTransactionBody tokenWipe = 31; + + /** + * Associate tokens to an account + */ + TokenAssociateTransactionBody tokenAssociate = 32; + + /** + * Dissociate tokens from an account + */ + TokenDissociateTransactionBody tokenDissociate = 33; + + /** + * Marks a schedule in the network's action queue as deleted, preventing it from executing + */ + ScheduleDeleteTransactionBody scheduleDelete = 34; } } diff --git a/services/schedule_create.proto b/services/schedule_create.proto index 3259b6e7..7eb85892 100644 --- a/services/schedule_create.proto +++ b/services/schedule_create.proto @@ -28,40 +28,66 @@ option java_multiple_files = true; import "basic_types.proto"; import "schedulable_transaction_body.proto"; -/* -Create a new schedule entity (or simply, schedule) in the network's action queue. Upon SUCCESS, the receipt contains -the `ScheduleID` of the created schedule. A schedule entity includes a scheduledTransactionBody to be executed when the schedule -has collected enough signing Ed25519 keys to satisfy the scheduled transaction's signing requirements. Upon `SUCCESS`, the receipt also -includes the scheduledTransactionID to use to query for the record of the scheduled transaction's execution (if it occurs). - -The expiration time of a schedule is always 30 minutes; it remains in state and can be queried using GetScheduleInfo until expiration, -no matter if the scheduled transaction has executed or marked deleted. - -If the adminKey field is omitted, the resulting schedule is immutable. If the adminKey is set, the ScheduleDelete -transaction can be used to mark it as deleted. The creator may also specify an optional memo whose UTF-8 encoding is at most 100 -bytes and does not include the zero byte is also supported. - -When a scheduled transaction whose schedule has collected enough signing keys is executed, the network only charges its payer the service fee, -and not the node and network fees. If the optional payerAccountID is set, the network charges this account. Otherwise it charges the -payer of the originating ScheduleCreate. - -Two ScheduleCreate transactions are identical if they are equal in all their fields other than payerAccountID. -(Here "equal" should be understood in the sense of gRPC object equality in the network software runtime. In particular, a gRPC object with -unknown fields is not equal to a gRPC object without -unknown fields, even if they agree on all known fields.) +/** + * Create a new schedule entity (or simply, schedule) in the network's action queue. + * Upon SUCCESS, the receipt contains the `ScheduleID` of the created schedule. A schedule + * entity includes a scheduledTransactionBody to be executed when the schedule has + * collected enough signing Ed25519 keys to satisfy the scheduled transaction's signing + * requirements. Upon `SUCCESS`, the receipt also includes the scheduledTransactionID to + * use to query for the record of the scheduled transaction's execution (if it occurs). + * + * The expiration time of a schedule is always 30 minutes; it remains in state and can be queried + * using GetScheduleInfo until expiration, no matter if the scheduled transaction has + * executed or marked deleted. + * + * If the adminKey field is omitted, the resulting schedule is immutable. If the + * adminKey is set, the ScheduleDelete transaction can be used to mark it as + * deleted. The creator may also specify an optional memo whose UTF-8 encoding is at most + * 100 bytes and does not include the zero byte is also supported. + * + * When a scheduled transaction whose schedule has collected enough signing keys is executed, the + * network only charges its payer the service fee, and not the node and network fees. If the + * optional payerAccountID is set, the network charges this account. Otherwise it charges + * the payer of the originating ScheduleCreate. + * + * Two ScheduleCreate transactions are identical if they are equal in all their + * fields other than payerAccountID. (Here "equal" should be understood in the sense of + * gRPC object equality in the network software runtime. In particular, a gRPC object with unknown fields is + * not equal to a gRPC object without unknown fields, even if they agree on all known fields.) + * + * A ScheduleCreate transaction that attempts to re-create an identical schedule already in + * state will receive a receipt with status IDENTICAL_SCHEDULE_ALREADY_CREATED; the receipt + * will include the ScheduleID of the extant schedule, which may be used in a subsequent + * ScheduleSign transaction. (The receipt will also include the TransactionID to + * use in querying for the receipt or record of the scheduled transaction.) + * + * Other notable response codes include, INVALID_ACCOUNT_ID, + * UNSCHEDULABLE_TRANSACTION, UNRESOLVABLE_REQUIRED_SIGNERS, + * INVALID_SIGNATURE. For more information please see the section of this documentation on + * the ResponseCode enum. + */ +message ScheduleCreateTransactionBody { + /** + * The scheduled transaction + */ + SchedulableTransactionBody scheduledTransactionBody = 1; -A ScheduleCreate transaction that attempts to re-create an identical schedule already in state will receive a receipt with status -IDENTICAL_SCHEDULE_ALREADY_CREATED; the receipt will include the ScheduleID of the extant schedule, which may be -used in a subsequent ScheduleSign transaction. (The receipt will also include the TransactionID to use in querying -for the receipt or record of the scheduled transaction.) + /** + * An optional memo with a UTF-8 encoding of no more than 100 bytes which does not contain the + * zero byte + */ + string memo = 2; -Other notable response codes include, INVALID_ACCOUNT_ID, UNSCHEDULABLE_TRANSACTION, UNRESOLVABLE_REQUIRED_SIGNERS, -INVALID_SIGNATURE. For more information please see the section of this documentation on the ResponseCode enum. -*/ + /** + * An optional Hedera key which can be used to sign a ScheduleDelete and remove the schedule + */ + Key adminKey = 3; -message ScheduleCreateTransactionBody { - SchedulableTransactionBody scheduledTransactionBody = 1; // The scheduled transaction - string memo = 2; // An optional memo with a UTF-8 encoding of no more than 100 bytes which does not contain the zero byte - Key adminKey = 3; // An optional Hedera key which can be used to sign a ScheduleDelete and remove the schedule - AccountID payerAccountID = 4; // An optional id of the account to be charged the service fee for the scheduled transaction at the consensus time that it executes (if ever); defaults to the ScheduleCreate payer if not given + /** + * An optional id of the account to be charged the service fee for the scheduled transaction at + * the consensus time that it executes (if ever); defaults to the ScheduleCreate payer if not + * given + */ + AccountID payerAccountID = 4; } diff --git a/services/schedule_delete.proto b/services/schedule_delete.proto index 15adbd50..1bab91bc 100644 --- a/services/schedule_delete.proto +++ b/services/schedule_delete.proto @@ -27,13 +27,19 @@ option java_multiple_files = true; import "basic_types.proto"; -/* -Marks a schedule in the network's action queue as deleted. Must be signed by the admin key of the target schedule. -A deleted schedule cannot receive any additional signing keys, nor will it be executed. - -Other notable response codes include, INVALID_SCHEDULE_ID, SCHEDULE_WAS_DELETED, SCHEDULE_WAS_EXECUTED, -SCHEDULE_IS_IMMUTABLE. For more information please see the section of this documentation on the ResponseCode enum. +/** + * Marks a schedule in the network's action queue as deleted. Must be signed by the admin key of the + * target schedule. A deleted schedule cannot receive any additional signing keys, nor will it be + * executed. + * + * Other notable response codes include, INVALID_SCHEDULE_ID, + * SCHEDULE_WAS_DELETED, SCHEDULE_WAS_EXECUTED, SCHEDULE_IS_IMMUTABLE. + * For more information please see the section of this documentation on the ResponseCode + * enum. */ message ScheduleDeleteTransactionBody { - ScheduleID scheduleID = 1; // The ID of the Scheduled Entity + /** + * The ID of the Scheduled Entity + */ + ScheduleID scheduleID = 1; } diff --git a/services/schedule_get_info.proto b/services/schedule_get_info.proto index 8775b997..fc8f45c6 100644 --- a/services/schedule_get_info.proto +++ b/services/schedule_get_info.proto @@ -31,39 +31,99 @@ import "query_header.proto"; import "response_header.proto"; import "schedulable_transaction_body.proto"; -/* -Gets information about a schedule in the network's action queue. - -Responds with INVALID_SCHEDULE_ID if the requested schedule doesn't exist. -*/ +/** + * Gets information about a schedule in the network's action queue. + * + * Responds with INVALID_SCHEDULE_ID if the requested schedule doesn't exist. + */ message ScheduleGetInfoQuery { - QueryHeader header = 1; // standard info sent from client to node including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - ScheduleID scheduleID = 2; // The id of the schedule to interrogate + /** + * standard info sent from client to node including the signed payment, and what kind of response + * is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The id of the schedule to interrogate + */ + ScheduleID scheduleID = 2; } -/* - Information summarizing schedule state -*/ +/** + * Information summarizing schedule state + */ message ScheduleInfo { - ScheduleID scheduleID = 1; // The id of the schedule + /** + * The id of the schedule + */ + ScheduleID scheduleID = 1; + oneof data { - Timestamp deletion_time = 2; // If the schedule has been deleted, the consensus time when this occurred - Timestamp execution_time = 3; // If the schedule has been executed, the consensus time when this occurred + /** + * If the schedule has been deleted, the consensus time when this occurred + */ + Timestamp deletion_time = 2; + + /** + * If the schedule has been executed, the consensus time when this occurred + */ + Timestamp execution_time = 3; } - Timestamp expirationTime = 4; // The time at which the schedule will expire - SchedulableTransactionBody scheduledTransactionBody = 5; // The scheduled transaction - string memo = 6; // The publicly visible memo of the schedule - Key adminKey = 7; // The key used to delete the schedule from state - KeyList signers = 8; // The Ed25519 keys the network deems to have signed the scheduled transaction - AccountID creatorAccountID = 9; // The id of the account that created the schedule - AccountID payerAccountID = 10; // The id of the account responsible for the service fee of the scheduled transaction - TransactionID scheduledTransactionID = 11; // The transaction id that will be used in the record of the scheduled transaction (if it executes) + + /** + * The time at which the schedule will expire + */ + Timestamp expirationTime = 4; + + /** + * The scheduled transaction + */ + SchedulableTransactionBody scheduledTransactionBody = 5; + + /** + * The publicly visible memo of the schedule + */ + string memo = 6; + + /** + * The key used to delete the schedule from state + */ + Key adminKey = 7; + + /** + * The Ed25519 keys the network deems to have signed the scheduled transaction + */ + KeyList signers = 8; + + /** + * The id of the account that created the schedule + */ + AccountID creatorAccountID = 9; + + /** + * The id of the account responsible for the service fee of the scheduled transaction + */ + AccountID payerAccountID = 10; + + /** + * The transaction id that will be used in the record of the scheduled transaction (if it + * executes) + */ + TransactionID scheduledTransactionID = 11; } -/* -Response wrapper for the ScheduleInfo -*/ +/** + * Response wrapper for the ScheduleInfo + */ message ScheduleGetInfoResponse { - ResponseHeader header = 1; // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - ScheduleInfo scheduleInfo = 2; // The information requested about this schedule instance + /** + * Standard response from node to client, including the requested fields: cost, or state proof, or + * both, or neither + */ + ResponseHeader header = 1; + + /** + * The information requested about this schedule instance + */ + ScheduleInfo scheduleInfo = 2; } diff --git a/services/schedule_service.proto b/services/schedule_service.proto index c8efb88b..2d32cf29 100644 --- a/services/schedule_service.proto +++ b/services/schedule_service.proto @@ -29,31 +29,49 @@ import "response.proto"; import "transaction_response.proto"; import "transaction.proto"; -/* -Transactions and queries for the Schedule Service -The Schedule Service allows transactions to be submitted without all the required signatures and allows anyone to provide the required signatures independently after a transaction has already been created. -Execution: -Scheduled Transactions are executed once all required signatures are collected and witnessed. Every time new signature is provided, a check is performed on the "readiness" of the execution. -The Scheduled Transaction will be executed immediately after the transaction that triggered it and will be externalised in a separate Transaction Record. -Transaction Record: -The timestamp of the Scheduled Transaction will be equal to consensusTimestamp + 1 nano, where consensusTimestamp is the timestamp of the transaction that triggered the execution. -The Transaction ID of the Scheduled Transaction will have the scheduled property set to true and inherit the transactionValidStart and accountID from the ScheduleCreate transaction. -The scheduleRef property of the transaction record will be populated with the ScheduleID of the Scheduled Transaction. -Post execution: -Once a given Scheduled Transaction executes, it will be removed from the ledger and any upcoming operation referring the ScheduleID will resolve to INVALID_SCHEDULE_ID. -Expiry: -Scheduled Transactions have a global expiry time txExpiryTimeSecs (Currently set to 30 minutes). If txExpiryTimeSecs pass and the Scheduled Transaction haven't yet executed, it will be removed from the ledger as if ScheduleDelete operation is executed. -*/ +/** + * Transactions and queries for the Schedule Service + * The Schedule Service allows transactions to be submitted without all the required signatures and + * allows anyone to provide the required signatures independently after a transaction has already + * been created. + * Execution: + * Scheduled Transactions are executed once all required signatures are collected and witnessed. + * Every time new signature is provided, a check is performed on the "readiness" of the execution. + * The Scheduled Transaction will be executed immediately after the transaction that triggered it + * and will be externalised in a separate Transaction Record. + * Transaction Record: + * The timestamp of the Scheduled Transaction will be equal to consensusTimestamp + 1 nano, where + * consensusTimestamp is the timestamp of the transaction that triggered the execution. + * The Transaction ID of the Scheduled Transaction will have the scheduled property set to true and + * inherit the transactionValidStart and accountID from the ScheduleCreate transaction. + * The scheduleRef property of the transaction record will be populated with the ScheduleID of the + * Scheduled Transaction. + * Post execution: + * Once a given Scheduled Transaction executes, it will be removed from the ledger and any upcoming + * operation referring the ScheduleID will resolve to INVALID_SCHEDULE_ID. + * Expiry: + * Scheduled Transactions have a global expiry time txExpiryTimeSecs (Currently set to 30 minutes). + * If txExpiryTimeSecs pass and the Scheduled Transaction haven't yet executed, it will be removed + * from the ledger as if ScheduleDelete operation is executed. + */ service ScheduleService { - // Creates a new Schedule by submitting the transaction + /** + * Creates a new Schedule by submitting the transaction + */ rpc createSchedule (Transaction) returns (TransactionResponse); - // Signs a new Schedule by submitting the transaction + /** + * Signs a new Schedule by submitting the transaction + */ rpc signSchedule (Transaction) returns (TransactionResponse); - // Deletes a new Schedule by submitting the transaction + /** + * Deletes a new Schedule by submitting the transaction + */ rpc deleteSchedule (Transaction) returns (TransactionResponse); - // Retrieves the metadata of a schedule entity + /** + * Retrieves the metadata of a schedule entity + */ rpc getScheduleInfo (Query) returns (Response); } diff --git a/services/schedule_sign.proto b/services/schedule_sign.proto index d4dcedc7..d379507d 100644 --- a/services/schedule_sign.proto +++ b/services/schedule_sign.proto @@ -27,17 +27,22 @@ option java_multiple_files = true; import "basic_types.proto"; -/* -Adds zero or more signing keys to a schedule. If the resulting set of signing keys satisfy the scheduled -transaction's signing requirements, it will be executed immediately after the triggering ScheduleSign. - -Upon SUCCESS, the receipt includes the scheduledTransactionID to use to query for the -record of the scheduled transaction's execution (if it occurs). - -Other notable response codes include INVALID_SCHEDULE_ID, SCHEDULE_WAS_DELETD, -INVALID_ACCOUNT_ID, UNRESOLVABLE_REQUIRED_SIGNERS, SOME_SIGNATURES_WERE_INVALID, -and NO_NEW_VALID_SIGNATURES. For more information please see the section of this -documentation on the ResponseCode enum. */ +/** + * Adds zero or more signing keys to a schedule. If the resulting set of signing keys satisfy the + * scheduled transaction's signing requirements, it will be executed immediately after the + * triggering ScheduleSign. + * + * Upon SUCCESS, the receipt includes the scheduledTransactionID to use to query + * for the record of the scheduled transaction's execution (if it occurs). + * + * Other notable response codes include INVALID_SCHEDULE_ID, SCHEDULE_WAS_DELETD, + * INVALID_ACCOUNT_ID, UNRESOLVABLE_REQUIRED_SIGNERS, + * SOME_SIGNATURES_WERE_INVALID, and NO_NEW_VALID_SIGNATURES. For more information + * please see the section of this documentation on the ResponseCode enum. + */ message ScheduleSignTransactionBody { - ScheduleID scheduleID = 1; // The id of the schedule to add signing keys to + /** + * The id of the schedule to add signing keys to + */ + ScheduleID scheduleID = 1; } diff --git a/services/smart_contract_service.proto b/services/smart_contract_service.proto index 54b6f7da..303ffac1 100644 --- a/services/smart_contract_service.proto +++ b/services/smart_contract_service.proto @@ -28,32 +28,65 @@ import "query.proto"; import "response.proto"; import "transaction.proto"; -/* -Transactions and queries for the file service. -*/ +/** + * Transactions and queries for the file service. + */ service SmartContractService { - // Creates a contract + /** + * Creates a contract + */ rpc createContract (Transaction) returns (TransactionResponse); - // Updates a contract with the content + + /** + * Updates a contract with the content + */ rpc updateContract (Transaction) returns (TransactionResponse); - // Calls a contract + + /** + * Calls a contract + */ rpc contractCallMethod (Transaction) returns (TransactionResponse); - // Retrieves the contract information + + /** + * Retrieves the contract information + */ rpc getContractInfo (Query) returns (Response); - // Calls a smart contract to be run on a single node + + /** + * Calls a smart contract to be run on a single node + */ rpc contractCallLocalMethod (Query) returns (Response); - // Retrieves the byte code of a contract + + /** + * Retrieves the byte code of a contract + */ rpc ContractGetBytecode (Query) returns (Response); - // Retrieves a contract by its Solidity address + + /** + * Retrieves a contract by its Solidity address + */ rpc getBySolidityID (Query) returns (Response); - // Always returns an empty record list, as contract accounts are never effective payers for transactions + + /** + * Always returns an empty record list, as contract accounts are never effective payers for + * transactions + */ rpc getTxRecordByContractID (Query) returns (Response) { option deprecated = true; }; - // Deletes a contract instance and transfers any remaining hbars to a specified receiver + + /** + * Deletes a contract instance and transfers any remaining hbars to a specified receiver + */ rpc deleteContract (Transaction) returns (TransactionResponse); - // Deletes a contract if the submitting account has network admin privileges + + /** + * Deletes a contract if the submitting account has network admin privileges + */ rpc systemDelete (Transaction) returns (TransactionResponse); - // Undeletes a contract if the submitting account has network admin privileges + + /** + * Undeletes a contract if the submitting account has network admin privileges + */ rpc systemUndelete (Transaction) returns (TransactionResponse); } diff --git a/services/system_delete.proto b/services/system_delete.proto index 3ea92019..011c6b97 100644 --- a/services/system_delete.proto +++ b/services/system_delete.proto @@ -28,13 +28,29 @@ option java_multiple_files = true; import "basic_types.proto"; import "timestamp.proto"; -/* -Delete a file or smart contract - can only be done with a Hedera administrative multisignature. When it is deleted, it immediately disappears from the system as seen by the user, but is still stored internally until the expiration time, at which time it is truly and permanently deleted. Until that time, it can be undeleted by the Hedera administrative multisignature. When a smart contract is deleted, the cryptocurrency account within it continues to exist, and is not affected by the expiration time here. -*/ +/** + * Delete a file or smart contract - can only be done with a Hedera administrative multisignature. + * When it is deleted, it immediately disappears from the system as seen by the user, but is still + * stored internally until the expiration time, at which time it is truly and permanently deleted. + * Until that time, it can be undeleted by the Hedera administrative multisignature. When a smart + * contract is deleted, the cryptocurrency account within it continues to exist, and is not affected + * by the expiration time here. + */ message SystemDeleteTransactionBody { oneof id { - FileID fileID = 1; // The file ID of the file to delete, in the format used in transactions - ContractID contractID = 2; // The contract ID instance to delete, in the format used in transactions + /** + * The file ID of the file to delete, in the format used in transactions + */ + FileID fileID = 1; + + /** + * The contract ID instance to delete, in the format used in transactions + */ + ContractID contractID = 2; } - TimestampSeconds expirationTime = 3; // The timestamp in seconds at which the "deleted" file should truly be permanently deleted + + /** + * The timestamp in seconds at which the "deleted" file should truly be permanently deleted + */ + TimestampSeconds expirationTime = 3; } diff --git a/services/system_undelete.proto b/services/system_undelete.proto index 33d7b9e4..39a4c9fd 100644 --- a/services/system_undelete.proto +++ b/services/system_undelete.proto @@ -27,12 +27,20 @@ option java_multiple_files = true; import "basic_types.proto"; -/* -Undelete a file or smart contract that was deleted by SystemDelete; requires a Hedera administrative multisignature. -*/ +/** + * Undelete a file or smart contract that was deleted by SystemDelete; requires a Hedera + * administrative multisignature. + */ message SystemUndeleteTransactionBody { oneof id { - FileID fileID = 1; // The file ID to undelete, in the format used in transactions - ContractID contractID = 2; // The contract ID instance to undelete, in the format used in transactions + /** + * The file ID to undelete, in the format used in transactions + */ + FileID fileID = 1; + + /** + * The contract ID instance to undelete, in the format used in transactions + */ + ContractID contractID = 2; } } diff --git a/services/throttle_definitions.proto b/services/throttle_definitions.proto index 73b14a3a..df86362a 100644 --- a/services/throttle_definitions.proto +++ b/services/throttle_definitions.proto @@ -27,29 +27,59 @@ option java_multiple_files = true; import "basic_types.proto"; -/* For details behind this throttling design, please see the docs/throttle-design.md -document in the Hedera Services repository. */ +/** + * For details behind this throttling design, please see the docs/throttle-design.md document + * in the Hedera Services repository. + */ -/* A set of operations which should be collectively throttled at a given milli-ops-per-second limit. */ +/** + * A set of operations which should be collectively throttled at a given milli-ops-per-second limit. + */ message ThrottleGroup { - repeated HederaFunctionality operations = 1; // The operations to be throttled - uint64 milliOpsPerSec = 2; // The number of total operations per second across the entire network, multiplied by 1000. So, to choose 3 operations per second (which on a network of 30 nodes is a tenth of an operation per second for each node), set milliOpsPerSec = 3000. And to choose 3.6 ops per second, use milliOpsPerSec = 3600. Minimum allowed value is 1, and maximum allowed value is 9223372. + /** + * The operations to be throttled + */ + repeated HederaFunctionality operations = 1; + + /** + * The number of total operations per second across the entire network, multiplied by 1000. So, to + * choose 3 operations per second (which on a network of 30 nodes is a tenth of an operation per + * second for each node), set milliOpsPerSec = 3000. And to choose 3.6 ops per second, use + * milliOpsPerSec = 3600. Minimum allowed value is 1, and maximum allowed value is 9223372. + */ + uint64 milliOpsPerSec = 2; } -/* A list of throttle groups that should all compete for the same internal bucket. */ +/** + * A list of throttle groups that should all compete for the same internal bucket. + */ message ThrottleBucket { - string name = 1; // A name for this bucket (primarily for use in logs) - uint64 burstPeriodMs = 2; // The number of milliseconds required for this bucket to drain completely when full. The product of this number and the least common multiple of the milliOpsPerSec values in this bucket must not exceed 9223372036. - repeated ThrottleGroup throttleGroups = 3; // The throttle groups competing for this bucket + /** + * A name for this bucket (primarily for use in logs) + */ + string name = 1; + + /** + * The number of milliseconds required for this bucket to drain completely when full. The product + * of this number and the least common multiple of the milliOpsPerSec values in this bucket must + * not exceed 9223372036. + */ + uint64 burstPeriodMs = 2; + + /** + * The throttle groups competing for this bucket + */ + repeated ThrottleGroup throttleGroups = 3; } -/* A list of throttle buckets which, simultaneously enforced, define the system's throttling policy. -
    -
  1. When an operation appears in more than one throttling bucket, all its buckets must have room -or it will be throttled.
    2. -
  2. An operation assigned to no buckets is always throttled.
    3. -
-*/ +/** + * A list of throttle buckets which, simultaneously enforced, define the system's throttling policy. + *
    + *
  1. When an operation appears in more than one throttling bucket, all its buckets must have room + * or it will be throttled.
    2. + *
  2. An operation assigned to no buckets is always throttled.
    3. + *
+ */ message ThrottleDefinitions { repeated ThrottleBucket throttleBuckets = 1; } diff --git a/services/timestamp.proto b/services/timestamp.proto index 93080df3..6777196d 100644 --- a/services/timestamp.proto +++ b/services/timestamp.proto @@ -25,14 +25,29 @@ package proto; option java_package = "com.hederahashgraph.api.proto.java"; option java_multiple_files = true; -/* An exact date and time. This is the same data structure as the protobuf Timestamp.proto (see the comments in https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto) */ +/** + * An exact date and time. This is the same data structure as the protobuf Timestamp.proto (see the + * comments in https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto) + */ message Timestamp { - int64 seconds = 1; // Number of complete seconds since the start of the epoch - int32 nanos = 2; // Number of nanoseconds since the start of the last second + /** + * Number of complete seconds since the start of the epoch + */ + int64 seconds = 1; + + /** + * Number of nanoseconds since the start of the last second + */ + int32 nanos = 2; } -/* An exact date and time, with a resolution of one second (no nanoseconds). */ +/** + * An exact date and time, with a resolution of one second (no nanoseconds). + */ message TimestampSeconds { - int64 seconds = 1; // Number of complete seconds since the start of the epoch + /** + * Number of complete seconds since the start of the epoch + */ + int64 seconds = 1; } diff --git a/services/token_associate.proto b/services/token_associate.proto index a2fe6ba4..bfbac1de 100644 --- a/services/token_associate.proto +++ b/services/token_associate.proto @@ -27,16 +27,30 @@ option java_multiple_files = true; import "basic_types.proto"; -/* Associates the provided account with the provided tokens. Must be signed by the provided Account's key. - If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. - If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. - If any of the provided tokens is not found, the transaction will resolve to INVALID_TOKEN_REF. - If any of the provided tokens has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. - If an association between the provided account and any of the tokens already exists, the transaction will resolve to TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT. - If the provided account's associations count exceed the constraint of maximum token associations per account, the transaction will resolve to TOKENS_PER_ACCOUNT_LIMIT_EXCEEDED. - On success, associations between the provided account and tokens are made and the account is ready to interact with the tokens. +/** + * Associates the provided account with the provided tokens. Must be signed by the provided + * Account's key. + * If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. + * If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. + * If any of the provided tokens is not found, the transaction will resolve to INVALID_TOKEN_REF. + * If any of the provided tokens has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. + * If an association between the provided account and any of the tokens already exists, the + * transaction will resolve to TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT. + * If the provided account's associations count exceed the constraint of maximum token associations + * per account, the transaction will resolve to TOKENS_PER_ACCOUNT_LIMIT_EXCEEDED. + * On success, associations between the provided account and tokens are made and the account is + * ready to interact with the tokens. */ message TokenAssociateTransactionBody { - AccountID account = 1; // The account to be associated with the provided tokens - repeated TokenID tokens = 2; // The tokens to be associated with the provided account. In the case of NON_FUNGIBLE_UNIQUE Type, once an account is associated, it can hold any number of NFTs (serial numbers) of that token type + /** + * The account to be associated with the provided tokens + */ + AccountID account = 1; + + /** + * The tokens to be associated with the provided account. In the case of NON_FUNGIBLE_UNIQUE + * Type, once an account is associated, it can hold any number of NFTs (serial numbers) of that + * token type + */ + repeated TokenID tokens = 2; } diff --git a/services/token_burn.proto b/services/token_burn.proto index 2ddd8a55..b8283e00 100644 --- a/services/token_burn.proto +++ b/services/token_burn.proto @@ -27,20 +27,40 @@ option java_multiple_files = true; import "basic_types.proto"; -/* -Burns tokens from the Token's treasury Account. If no Supply Key is defined, the transaction will resolve to TOKEN_HAS_NO_SUPPLY_KEY. -The operation decreases the Total Supply of the Token. Total supply cannot go below zero. -The amount provided must be in the lowest denomination possible. Example: -Token A has 2 decimals. In order to burn 100 tokens, one must provide amount of 10000. In order to burn 100.55 tokens, one must provide amount of 10055. -For non fungible tokens the transaction body accepts serialNumbers list of integers as a parameter. - -If neither the amount nor the serialNumbers get filled, a INVALID_TOKEN_BURN_AMOUNT response code will be returned. -If both amount and serialNumbers get filled, a INVALID_TRANSACTION_BODY response code will be returned. -If the serialNumbers' list count is greater than the batch size limit global dynamic property, a BATCH_SIZE_LIMIT_EXCEEDED response code will be returned. -If the serialNumbers list contains a non-positive integer as a serial number, a INVALID_NFT_ID response code will be returned. -*/ +/** + * Burns tokens from the Token's treasury Account. If no Supply Key is defined, the transaction will + * resolve to TOKEN_HAS_NO_SUPPLY_KEY. + * The operation decreases the Total Supply of the Token. Total supply cannot go below zero. + * The amount provided must be in the lowest denomination possible. Example: + * Token A has 2 decimals. In order to burn 100 tokens, one must provide amount of 10000. In order + * to burn 100.55 tokens, one must provide amount of 10055. + * For non fungible tokens the transaction body accepts serialNumbers list of integers as a parameter. + * + * If neither the amount nor the serialNumbers get filled, a INVALID_TOKEN_BURN_AMOUNT response code + * will be returned. + * If both amount and serialNumbers get filled, a INVALID_TRANSACTION_BODY response code will be + * returned. + * If the serialNumbers' list count is greater than the batch size limit global dynamic property, a + * BATCH_SIZE_LIMIT_EXCEEDED response code will be returned. + * If the serialNumbers list contains a non-positive integer as a serial number, a INVALID_NFT_ID + * response code will be returned. + */ message TokenBurnTransactionBody { - TokenID token = 1; // The token for which to burn tokens. If token does not exist, transaction results in INVALID_TOKEN_ID - uint64 amount = 2; // Applicable to tokens of type FUNGIBLE_COMMON. The amount to burn from the Treasury Account. Amount must be a positive non-zero number, not bigger than the token balance of the treasury account (0; balance], represented in the lowest denomination. - repeated int64 serialNumbers = 3; // Applicable to tokens of type NON_FUNGIBLE_UNIQUE. The list of serial numbers to be burned. + /** + * The token for which to burn tokens. If token does not exist, transaction results in + * INVALID_TOKEN_ID + */ + TokenID token = 1; + + /** + * Applicable to tokens of type FUNGIBLE_COMMON. The amount to burn from the Treasury Account. + * Amount must be a positive non-zero number, not bigger than the token balance of the treasury + * account (0; balance], represented in the lowest denomination. + */ + uint64 amount = 2; + + /** + * Applicable to tokens of type NON_FUNGIBLE_UNIQUE. The list of serial numbers to be burned. + */ + repeated int64 serialNumbers = 3; } diff --git a/services/token_create.proto b/services/token_create.proto index fad90f63..42bb2dd6 100644 --- a/services/token_create.proto +++ b/services/token_create.proto @@ -30,49 +30,165 @@ import "basic_types.proto"; import "custom_fees.proto"; import "timestamp.proto"; -/* -Create a new token. After the token is created, the Token ID for it is in the receipt. -The specified Treasury Account is receiving the initial supply of tokens as-well as the tokens from the Token Mint operation once executed. The balance of the treasury account is decreased when the Token Burn operation is executed. +/** + * Create a new token. After the token is created, the Token ID for it is in the receipt. + * The specified Treasury Account is receiving the initial supply of tokens as-well as the tokens + * from the Token Mint operation once executed. The balance of the treasury account is decreased + * when the Token Burn operation is executed. + * + * The initialSupply is the initial supply of the smallest parts of a token (like a + * tinybar, not an hbar). These are the smallest units of the token which may be transferred. + * + * The supply can change over time. If the total supply at some moment is S parts of tokens, + * and the token is using D decimals, then S must be less than or equal to + * 263-1, which is 9,223,372,036,854,775,807. The number of whole tokens (not parts) will + * be S / 10D. + * + * If decimals is 8 or 11, then the number of whole tokens can be at most a few billions or + * millions, respectively. For example, it could match Bitcoin (21 million whole tokens with 8 + * decimals) or hbars (50 billion whole tokens with 8 decimals). It could even match Bitcoin with + * milli-satoshis (21 million whole tokens with 11 decimals). + * + * Note that a created token is immutable if the adminKey is omitted. No property of + * an immutable token can ever change, with the sole exception of its expiry. Anyone can pay to + * extend the expiry time of an immutable token. + * + * A token can be either FUNGIBLE_COMMON or NON_FUNGIBLE_UNIQUE, based on its + * TokenType. If it has been omitted, FUNGIBLE_COMMON type is used. + * + * A token can have either INFINITE or FINITE supply type, based on its + * TokenType. If it has been omitted, INFINITE type is used. + * + * If a FUNGIBLE TokenType is used, initialSupply should explicitly be set to a + * non-negative. If not, the transaction will resolve to INVALID_TOKEN_INITIAL_SUPPLY. + * + * If a NON_FUNGIBLE_UNIQUE TokenType is used, initialSupply should explicitly be set + * to 0. If not, the transaction will resolve to INVALID_TOKEN_INITIAL_SUPPLY. + * + * If an INFINITE TokenSupplyType is used, maxSupply should explicitly be set to 0. If + * it is not 0, the transaction will resolve to INVALID_TOKEN_MAX_SUPPLY. + * + * If a FINITE TokenSupplyType is used, maxSupply should be explicitly set to a + * non-negative value. If it is not, the transaction will resolve to INVALID_TOKEN_MAX_SUPPLY. + */ +message TokenCreateTransactionBody { + /** + * The publicly visible name of the token, limited to a UTF-8 encoding of + * length tokens.maxSymbolUtf8Bytes. + */ + string name = 1; -The initialSupply is the initial supply of the smallest parts of a token (like a tinybar, not an hbar). These are the smallest units of the token which may be transferred. + /** + * The publicly visible token symbol, limited to a UTF-8 encoding of length + * tokens.maxTokenNameUtf8Bytes. + */ + string symbol = 2; -The supply can change over time. If the total supply at some moment is S parts of tokens, and the token is using D decimals, then S must be less than or equal to 263-1, which is 9,223,372,036,854,775,807. The number of whole tokens (not parts) will be S / 10D. + /** + * For tokens of type FUNGIBLE_COMMON - the number of decimal places a + * token is divisible by. For tokens of type NON_FUNGIBLE_UNIQUE - value + * must be 0 + */ + uint32 decimals = 3; -If decimals is 8 or 11, then the number of whole tokens can be at most a few billions or millions, respectively. For example, it could match Bitcoin (21 million whole tokens with 8 decimals) or hbars (50 billion whole tokens with 8 decimals). It could even match Bitcoin with milli-satoshis (21 million whole tokens with 11 decimals). + /** + * Specifies the initial supply of tokens to be put in circulation. The + * initial supply is sent to the Treasury Account. The supply is in the + * lowest denomination possible. In the case for NON_FUNGIBLE_UNIQUE Type + * the value must be 0 + */ + uint64 initialSupply = 4; -Note that a created token is immutable if the adminKey is omitted. No property of an immutable token can ever change, with the sole exception of its expiry. Anyone can pay to extend the expiry time of an immutable token. + /** + * The account which will act as a treasury for the token. This account + * will receive the specified initial supply or the newly minted NFTs in + * the case for NON_FUNGIBLE_UNIQUE Type + */ + AccountID treasury = 5; -A token can be either FUNGIBLE_COMMON or NON_FUNGIBLE_UNIQUE, based on its TokenType. If it has been omitted, FUNGIBLE_COMMON type is used. + /** + * The key which can perform update/delete operations on the token. If empty, the token can be + * perceived as immutable (not being able to be updated/deleted) + */ + Key adminKey = 6; -A token can have either INFINITE or FINITE supply type, based on its TokenType. If it has been omitted, INFINITE type is used. + /** + * The key which can grant or revoke KYC of an account for the token's transactions. If empty, + * KYC is not required, and KYC grant or revoke operations are not possible. + */ + Key kycKey = 7; -If a FUNGIBLE TokenType is used, initialSupply should explicitly be set to a non-negative. If not, the transaction will resolve to INVALID_TOKEN_INITIAL_SUPPLY. + /** + * The key which can sign to freeze or unfreeze an account for token transactions. If empty, + * freezing is not possible + */ + Key freezeKey = 8; -If a NON_FUNGIBLE_UNIQUE TokenType is used, initialSupply should explicitly be set to 0. If not, the transaction will resolve to INVALID_TOKEN_INITIAL_SUPPLY. + /** + * The key which can wipe the token balance of an account. If empty, wipe is not possible + */ + Key wipeKey = 9; -If an INFINITE TokenSupplyType is used, maxSupply should explicitly be set to 0. If it is not 0, the transaction will resolve to INVALID_TOKEN_MAX_SUPPLY. + /** + * The key which can change the supply of a token. The key is used to sign Token Mint/Burn + * operations + */ + Key supplyKey = 10; -If a FINITE TokenSupplyType is used, maxSupply should be explicitly set to a non-negative value. If it is not, the transaction will resolve to INVALID_TOKEN_MAX_SUPPLY. - */ -message TokenCreateTransactionBody { - string name = 1; // The publicly visible name of the token, limited to a UTF-8 encoding of length tokens.maxSymbolUtf8Bytes. - string symbol = 2; // The publicly visible token symbol, limited to a UTF-8 encoding of length tokens.maxTokenNameUtf8Bytes. - uint32 decimals = 3; // For tokens of type FUNGIBLE_COMMON - the number of decimal places a token is divisible by. For tokens of type NON_FUNGIBLE_UNIQUE - value must be 0 - uint64 initialSupply = 4; // Specifies the initial supply of tokens to be put in circulation. The initial supply is sent to the Treasury Account. The supply is in the lowest denomination possible. In the case for NON_FUNGIBLE_UNIQUE Type the value must be 0 - AccountID treasury = 5; // The account which will act as a treasury for the token. This account will receive the specified initial supply or the newly minted NFTs in the case for NON_FUNGIBLE_UNIQUE Type - Key adminKey = 6; // The key which can perform update/delete operations on the token. If empty, the token can be perceived as immutable (not being able to be updated/deleted) - Key kycKey = 7; // The key which can grant or revoke KYC of an account for the token's transactions. If empty, KYC is not required, and KYC grant or revoke operations are not possible. - Key freezeKey = 8; // The key which can sign to freeze or unfreeze an account for token transactions. If empty, freezing is not possible - Key wipeKey = 9; // The key which can wipe the token balance of an account. If empty, wipe is not possible - Key supplyKey = 10; // The key which can change the supply of a token. The key is used to sign Token Mint/Burn operations - bool freezeDefault = 11; // The default Freeze status (frozen or unfrozen) of Hedera accounts relative to this token. If true, an account must be unfrozen before it can receive the token - Timestamp expiry = 13; // The epoch second at which the token should expire; if an auto-renew account and period are specified, this is coerced to the current epoch second plus the autoRenewPeriod - AccountID autoRenewAccount = 14; // An account which will be automatically charged to renew the token's expiration, at autoRenewPeriod interval - Duration autoRenewPeriod = 15; // The interval at which the auto-renew account will be charged to extend the token's expiry - string memo = 16; // The memo associated with the token (UTF-8 encoding max 100 bytes) - TokenType tokenType = 17; // IWA compatibility. Specifies the token type. Defaults to FUNGIBLE_COMMON - TokenSupplyType supplyType = 18; // IWA compatibility. Specified the token supply type. Defaults to INFINITE - int64 maxSupply = 19; // IWA Compatibility. Depends on TokenSupplyType. For tokens of type FUNGIBLE_COMMON - the maximum number of tokens that can be in circulation. For tokens of type NON_FUNGIBLE_UNIQUE - the maximum number of NFTs (serial numbers) that can be minted. This field can never be changed! - Key fee_schedule_key = 20; // The key which can change the token's custom fee schedule; must sign a TokenFeeScheduleUpdate transaction - repeated CustomFee custom_fees = 21; // The custom fees to be assessed during a CryptoTransfer that transfers units of this token + /** + * The default Freeze status (frozen or unfrozen) of Hedera accounts relative to this token. If + * true, an account must be unfrozen before it can receive the token + */ + bool freezeDefault = 11; + + /** + * The epoch second at which the token should expire; if an auto-renew account and period are + * specified, this is coerced to the current epoch second plus the autoRenewPeriod + */ + Timestamp expiry = 13; + + /** + * An account which will be automatically charged to renew the token's expiration, at + * autoRenewPeriod interval + */ + AccountID autoRenewAccount = 14; + + /** + * The interval at which the auto-renew account will be charged to extend the token's expiry + */ + Duration autoRenewPeriod = 15; + + /** + * The memo associated with the token (UTF-8 encoding max 100 bytes) + */ + string memo = 16; + + /** + * IWA compatibility. Specifies the token type. Defaults to FUNGIBLE_COMMON + */ + TokenType tokenType = 17; + + /** + * IWA compatibility. Specified the token supply type. Defaults to INFINITE + */ + TokenSupplyType supplyType = 18; + + /** + * IWA Compatibility. Depends on TokenSupplyType. For tokens of type FUNGIBLE_COMMON - the + * maximum number of tokens that can be in circulation. For tokens of type NON_FUNGIBLE_UNIQUE - + * the maximum number of NFTs (serial numbers) that can be minted. This field can never be + * changed! + */ + int64 maxSupply = 19; + + /** + * The key which can change the token's custom fee schedule; must sign a TokenFeeScheduleUpdate + * transaction + */ + Key fee_schedule_key = 20; + + /** + * The custom fees to be assessed during a CryptoTransfer that transfers units of this token + */ + repeated CustomFee custom_fees = 21; } diff --git a/services/token_delete.proto b/services/token_delete.proto index 2e9ca902..cd4ba0a4 100644 --- a/services/token_delete.proto +++ b/services/token_delete.proto @@ -27,10 +27,17 @@ option java_multiple_files = true; import "basic_types.proto"; -/* - Marks a token as deleted, though it will remain in the ledger. - The operation must be signed by the specified Admin Key of the Token. If admin key is not set, Transaction will result in TOKEN_IS_IMMUTABlE. - Once deleted update, mint, burn, wipe, freeze, unfreeze, grant kyc, revoke kyc and token transfer transactions will resolve to TOKEN_WAS_DELETED. */ +/** + * Marks a token as deleted, though it will remain in the ledger. + * The operation must be signed by the specified Admin Key of the Token. If + * admin key is not set, Transaction will result in TOKEN_IS_IMMUTABlE. + * Once deleted update, mint, burn, wipe, freeze, unfreeze, grant kyc, revoke + * kyc and token transfer transactions will resolve to TOKEN_WAS_DELETED. + */ message TokenDeleteTransactionBody { - TokenID token = 1; // The token to be deleted. If invalid token is specified, transaction will result in INVALID_TOKEN_ID + /** + * The token to be deleted. If invalid token is specified, transaction will + * result in INVALID_TOKEN_ID + */ + TokenID token = 1; } diff --git a/services/token_dissociate.proto b/services/token_dissociate.proto index bd882820..e7d9d6d9 100644 --- a/services/token_dissociate.proto +++ b/services/token_dissociate.proto @@ -27,18 +27,31 @@ option java_multiple_files = true; import "basic_types.proto"; -/* Dissociates the provided account with the provided tokens. Must be signed by the provided Account's key. - If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. - If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. - If any of the provided tokens is not found, the transaction will resolve to INVALID_TOKEN_REF. - If any of the provided tokens has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. - If an association between the provided account and any of the tokens does not exist, the transaction will resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. - If a token has not been deleted and has not expired, and the user has a nonzero balance, the transaction will resolve to TRANSACTION_REQUIRES_ZERO_TOKEN_BALANCES. - If a fungible token has expired, the user can disassociate even if their token balance is not zero. - If a non fungible token has expired, the user can not disassociate if their token balance is not zero. The transaction will resolve to TRANSACTION_REQUIRED_ZERO_TOKEN_BALANCES. - On success, associations between the provided account and tokens are removed. +/** + * Dissociates the provided account with the provided tokens. Must be signed by the provided + * Account's key. + * If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. + * If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. + * If any of the provided tokens is not found, the transaction will resolve to INVALID_TOKEN_REF. + * If any of the provided tokens has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. + * If an association between the provided account and any of the tokens does not exist, the + * transaction will resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. + * If a token has not been deleted and has not expired, and the user has a nonzero balance, the + * transaction will resolve to TRANSACTION_REQUIRES_ZERO_TOKEN_BALANCES. + * If a fungible token has expired, the user can disassociate even if their token balance is + * not zero. + * If a non fungible token has expired, the user can not disassociate if their token + * balance is not zero. The transaction will resolve to TRANSACTION_REQUIRED_ZERO_TOKEN_BALANCES. + * On success, associations between the provided account and tokens are removed. */ message TokenDissociateTransactionBody { - AccountID account = 1; // The account to be dissociated with the provided tokens - repeated TokenID tokens = 2; // The tokens to be dissociated with the provided account + /** + * The account to be dissociated with the provided tokens + */ + AccountID account = 1; + + /** + * The tokens to be dissociated with the provided account + */ + repeated TokenID tokens = 2; } diff --git a/services/token_fee_schedule_update.proto b/services/token_fee_schedule_update.proto index f0b743b4..883d9cdf 100644 --- a/services/token_fee_schedule_update.proto +++ b/services/token_fee_schedule_update.proto @@ -28,15 +28,24 @@ option java_multiple_files = true; import "basic_types.proto"; import "custom_fees.proto"; -/* At consensus, updates a token type's fee schedule to the given list of custom fees. - -If the target token type has no fee_schedule_key, resolves to TOKEN_HAS_NO_FEE_SCHEDULE_KEY. -Otherwise this transaction must be signed to the fee_schedule_key, or the transaction will -resolve to INVALID_SIGNATURE. - -If the custom_fees list is empty, clears the fee schedule or resolves to -CUSTOM_SCHEDULE_ALREADY_HAS_NO_FEES if the fee schedule was already empty. */ +/** + * At consensus, updates a token type's fee schedule to the given list of custom fees. + * + * If the target token type has no fee_schedule_key, resolves to TOKEN_HAS_NO_FEE_SCHEDULE_KEY. + * Otherwise this transaction must be signed to the fee_schedule_key, or the transaction will + * resolve to INVALID_SIGNATURE. + * + * If the custom_fees list is empty, clears the fee schedule or resolves to + * CUSTOM_SCHEDULE_ALREADY_HAS_NO_FEES if the fee schedule was already empty. + */ message TokenFeeScheduleUpdateTransactionBody { - TokenID token_id = 1; // The token whose fee schedule is to be updated - repeated CustomFee custom_fees = 2; // The new custom fees to be assessed during a CryptoTransfer that transfers units of this token + /** + * The token whose fee schedule is to be updated + */ + TokenID token_id = 1; + + /** + * The new custom fees to be assessed during a CryptoTransfer that transfers units of this token + */ + repeated CustomFee custom_fees = 2; } diff --git a/services/token_freeze_account.proto b/services/token_freeze_account.proto index f0ff2895..6c020783 100644 --- a/services/token_freeze_account.proto +++ b/services/token_freeze_account.proto @@ -27,16 +27,27 @@ option java_multiple_files = true; import "basic_types.proto"; -/* Freezes transfers of the specified token for the account. Must be signed by the Token's freezeKey. - If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. - If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. - If the provided token is not found, the transaction will resolve to INVALID_TOKEN_ID. - If the provided token has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. - If an Association between the provided token and account is not found, the transaction will resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. - If no Freeze Key is defined, the transaction will resolve to TOKEN_HAS_NO_FREEZE_KEY. - Once executed the Account is marked as Frozen and will not be able to receive or send tokens unless unfrozen. The operation is idempotent. +/** + * Freezes transfers of the specified token for the account. Must be signed by the Token's freezeKey. + * If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. + * If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. + * If the provided token is not found, the transaction will resolve to INVALID_TOKEN_ID. + * If the provided token has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. + * If an Association between the provided token and account is not found, the transaction will + * resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. + * If no Freeze Key is defined, the transaction will resolve to TOKEN_HAS_NO_FREEZE_KEY. + * Once executed the Account is marked as Frozen and will not be able to receive or send tokens + * unless unfrozen. The operation is idempotent. */ message TokenFreezeAccountTransactionBody { - TokenID token = 1; // The token for which this account will be frozen. If token does not exist, transaction results in INVALID_TOKEN_ID - AccountID account = 2; // The account to be frozen + /** + * The token for which this account will be frozen. If token does not exist, transaction results + * in INVALID_TOKEN_ID + */ + TokenID token = 1; + + /** + * The account to be frozen + */ + AccountID account = 2; } diff --git a/services/token_get_account_nft_infos.proto b/services/token_get_account_nft_infos.proto index f70bab08..b7afbf79 100644 --- a/services/token_get_account_nft_infos.proto +++ b/services/token_get_account_nft_infos.proto @@ -30,14 +30,18 @@ import "token_get_nft_info.proto"; import "query_header.proto"; import "response_header.proto"; -/* Applicable only to tokens of type NON_FUNGIBLE_UNIQUE. Gets info on NFTs N through M owned by the specified accountId. - * Example: If Account A owns 5 NFTs (might be of different Token Entity), having start=0 and end=5 will return all of the NFTs - * +/** + * Applicable only to tokens of type NON_FUNGIBLE_UNIQUE. Gets info on NFTs N through M owned by the + * specified accountId. + * Example: If Account A owns 5 NFTs (might be of different Token Entity), having start=0 and end=5 + * will return all of the NFTs + * * INVALID_QUERY_RANGE response code will be returned if: * 1) Start > End * 2) Start and End indices are non-positive * 3) Start and End indices are out of boundaries for the retrieved nft list - * 4) The range between Start and End is bigger than the global dynamic property for maximum query range + * 4) The range between Start and End is bigger than the global dynamic property for maximum query + * range * * NOT_SUPPORTED response code will be returned if the queried token is of type FUNGIBLE_COMMON * @@ -46,13 +50,42 @@ import "response_header.proto"; * ACCOUNT_DELETED response code will be returned if the queried account has been deleted */ message TokenGetAccountNftInfosQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - AccountID accountID = 2; // The Account for which information is requested - int64 start = 3; // Specifies the start index (inclusive) of the range of NFTs to query for. Value must be in the range [0; ownedNFTs-1] - int64 end = 4; // Specifies the end index (exclusive) of the range of NFTs to query for. Value must be in the range (start; ownedNFTs] + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The Account for which information is requested + */ + AccountID accountID = 2; + + /** + * Specifies the start index (inclusive) of the range of NFTs to query for. Value must be in the + * range [0; ownedNFTs-1] + */ + int64 start = 3; + + /** + * Specifies the end index (exclusive) of the range of NFTs to query for. Value must be in the + * range (start; ownedNFTs] + */ + int64 end = 4; } +/** + * UNDOCUMENTED + */ message TokenGetAccountNftInfosResponse { - ResponseHeader header = 1; // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - repeated TokenNftInfo nfts = 2; // List of NFTs associated to the account + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + + /** + * List of NFTs associated to the account + */ + repeated TokenNftInfo nfts = 2; } diff --git a/services/token_get_info.proto b/services/token_get_info.proto index f5230516..cc855d96 100644 --- a/services/token_get_info.proto +++ b/services/token_get_info.proto @@ -32,41 +32,170 @@ import "response_header.proto"; import "timestamp.proto"; import "duration.proto"; -/* Gets information about Token instance */ +/** + * Gets information about Token instance + */ message TokenGetInfoQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither) - TokenID token = 2; // The token for which information is requested. If invalid token is provided, INVALID_TOKEN_ID response is returned. + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither) + */ + QueryHeader header = 1; + + /** + * The token for which information is requested. If invalid token is provided, INVALID_TOKEN_ID + * response is returned. + */ + TokenID token = 2; } -/* The metadata about a Token instance */ +/** + * The metadata about a Token instance + */ message TokenInfo { - TokenID tokenId = 1; // ID of the token instance - string name = 2; // The name of the token. It is a string of ASCII only characters - string symbol = 3; // The symbol of the token. It is a UTF-8 capitalized alphabetical string - uint32 decimals = 4; // The number of decimal places a token is divisible by. Always 0 for tokens of type NON_FUNGIBLE_UNIQUE - uint64 totalSupply = 5; // For tokens of type FUNGIBLE_COMMON - the total supply of tokens that are currently in circulation. For tokens of type NON_FUNGIBLE_UNIQUE - the number of NFTs created of this token instance - AccountID treasury = 6; // The ID of the account which is set as Treasury - Key adminKey = 7; // The key which can perform update/delete operations on the token. If empty, the token can be perceived as immutable (not being able to be updated/deleted) - Key kycKey = 8; // The key which can grant or revoke KYC of an account for the token's transactions. If empty, KYC is not required, and KYC grant or revoke operations are not possible. - Key freezeKey = 9; // The key which can freeze or unfreeze an account for token transactions. If empty, freezing is not possible - Key wipeKey = 10; // The key which can wipe token balance of an account. If empty, wipe is not possible - Key supplyKey = 11; // The key which can change the supply of a token. The key is used to sign Token Mint/Burn operations - TokenFreezeStatus defaultFreezeStatus = 12; // The default Freeze status (not applicable, frozen or unfrozen) of Hedera accounts relative to this token. FreezeNotApplicable is returned if Token Freeze Key is empty. Frozen is returned if Token Freeze Key is set and defaultFreeze is set to true. Unfrozen is returned if Token Freeze Key is set and defaultFreeze is set to false - TokenKycStatus defaultKycStatus = 13; // The default KYC status (KycNotApplicable or Revoked) of Hedera accounts relative to this token. KycNotApplicable is returned if KYC key is not set, otherwise Revoked - bool deleted = 14; // Specifies whether the token was deleted or not - AccountID autoRenewAccount = 15; // An account which will be automatically charged to renew the token's expiration, at autoRenewPeriod interval - Duration autoRenewPeriod = 16; // The interval at which the auto-renew account will be charged to extend the token's expiry - Timestamp expiry = 17; // The epoch second at which the token will expire - string memo = 18; // The memo associated with the token - TokenType tokenType = 19; // The token type - TokenSupplyType supplyType = 20; // The token supply type - int64 maxSupply = 21; // For tokens of type FUNGIBLE_COMMON - The Maximum number of fungible tokens that can be in circulation. For tokens of type NON_FUNGIBLE_UNIQUE - the maximum number of NFTs (serial numbers) that can be in circulation - Key fee_schedule_key = 22; // The key which can change the custom fee schedule of the token; if not set, the fee schedule is immutable - repeated CustomFee custom_fees = 23; // The custom fees to be assessed during a CryptoTransfer that transfers units of this token + /** + * ID of the token instance + */ + TokenID tokenId = 1; + + /** + * The name of the token. It is a string of ASCII only characters + */ + string name = 2; + + /** + * The symbol of the token. It is a UTF-8 capitalized alphabetical string + */ + string symbol = 3; + + /** + * The number of decimal places a token is divisible by. Always 0 for tokens of type + * NON_FUNGIBLE_UNIQUE + */ + uint32 decimals = 4; + + /** + * For tokens of type FUNGIBLE_COMMON - the total supply of tokens that are currently in + * circulation. For tokens of type NON_FUNGIBLE_UNIQUE - the number of NFTs created of this + * token instance + */ + uint64 totalSupply = 5; + + /** + * The ID of the account which is set as Treasury + */ + AccountID treasury = 6; + + /** + * The key which can perform update/delete operations on the token. If empty, the token can be + * perceived as immutable (not being able to be updated/deleted) + */ + Key adminKey = 7; + + /** + * The key which can grant or revoke KYC of an account for the token's transactions. If empty, + * KYC is not required, and KYC grant or revoke operations are not possible. + */ + Key kycKey = 8; + + /** + * The key which can freeze or unfreeze an account for token transactions. If empty, freezing is + * not possible + */ + Key freezeKey = 9; + + /** + * The key which can wipe token balance of an account. If empty, wipe is not possible + */ + Key wipeKey = 10; + + /** + * The key which can change the supply of a token. The key is used to sign Token Mint/Burn + * operations + */ + Key supplyKey = 11; + + /** + * The default Freeze status (not applicable, frozen or unfrozen) of Hedera accounts relative to + * this token. FreezeNotApplicable is returned if Token Freeze Key is empty. Frozen is returned + * if Token Freeze Key is set and defaultFreeze is set to true. Unfrozen is returned if Token + * Freeze Key is set and defaultFreeze is set to false + */ + TokenFreezeStatus defaultFreezeStatus = 12; + + /** + * The default KYC status (KycNotApplicable or Revoked) of Hedera accounts relative to this + * token. KycNotApplicable is returned if KYC key is not set, otherwise Revoked + */ + TokenKycStatus defaultKycStatus = 13; + + /** + * Specifies whether the token was deleted or not + */ + bool deleted = 14; + + /** + * An account which will be automatically charged to renew the token's expiration, at + * autoRenewPeriod interval + */ + AccountID autoRenewAccount = 15; + + /** + * The interval at which the auto-renew account will be charged to extend the token's expiry + */ + Duration autoRenewPeriod = 16; + + /** + * The epoch second at which the token will expire + */ + Timestamp expiry = 17; + + /** + * The memo associated with the token + */ + string memo = 18; + + /** + * The token type + */ + TokenType tokenType = 19; + + /** + * The token supply type + */ + TokenSupplyType supplyType = 20; + + /** + * For tokens of type FUNGIBLE_COMMON - The Maximum number of fungible tokens that can be in + * circulation. For tokens of type NON_FUNGIBLE_UNIQUE - the maximum number of NFTs (serial + * numbers) that can be in circulation + */ + int64 maxSupply = 21; + + /** + * The key which can change the custom fee schedule of the token; if not set, the fee schedule + * is immutable + */ + Key fee_schedule_key = 22; + + /** + * The custom fees to be assessed during a CryptoTransfer that transfers units of this token + */ + repeated CustomFee custom_fees = 23; } -/* Response when the client sends the node TokenGetInfoQuery */ +/** + * Response when the client sends the node TokenGetInfoQuery + */ message TokenGetInfoResponse { - ResponseHeader header = 1; // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - TokenInfo tokenInfo = 2; // The information requested about this token instance + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + + /** + * The information requested about this token instance + */ + TokenInfo tokenInfo = 2; } diff --git a/services/token_get_nft_info.proto b/services/token_get_nft_info.proto index 63ebca85..b6c4ecad 100644 --- a/services/token_get_nft_info.proto +++ b/services/token_get_nft_info.proto @@ -30,26 +30,75 @@ import "query_header.proto"; import "response_header.proto"; import "timestamp.proto"; -/* Represents an NFT on the Ledger */ +/** + * Represents an NFT on the Ledger + */ message NftID { - TokenID tokenID = 1; // The (non-fungible) token of which this NFT is an instance - int64 serialNumber = 2; // The unique identifier of this instance + /** + * The (non-fungible) token of which this NFT is an instance + */ + TokenID tokenID = 1; + + /** + * The unique identifier of this instance + */ + int64 serialNumber = 2; } -/* Applicable only to tokens of type NON_FUNGIBLE_UNIQUE. Gets info on a NFT for a given TokenID (of type NON_FUNGIBLE_UNIQUE) and serial number */ +/** + * Applicable only to tokens of type NON_FUNGIBLE_UNIQUE. Gets info on a NFT for a given TokenID (of + * type NON_FUNGIBLE_UNIQUE) and serial number + */ message TokenGetNftInfoQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - NftID nftID = 2; // The ID of the NFT + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The ID of the NFT + */ + NftID nftID = 2; } +/** + * UNDOCUMENTED + */ message TokenNftInfo { - NftID nftID = 1; // The ID of the NFT - AccountID accountID = 2; // The current owner of the NFT - Timestamp creationTime = 3; // The effective consensus timestamp at which the NFT was minted - bytes metadata = 4; // Represents the unique metadata of the NFT + /** + * The ID of the NFT + */ + NftID nftID = 1; + + /** + * The current owner of the NFT + */ + AccountID accountID = 2; + + /** + * The effective consensus timestamp at which the NFT was minted + */ + Timestamp creationTime = 3; + + /** + * Represents the unique metadata of the NFT + */ + bytes metadata = 4; } +/** + * UNDOCUMENTED + */ message TokenGetNftInfoResponse { - ResponseHeader header = 1; // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - TokenNftInfo nft = 2; // The information about this NFT + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + + /** + * The information about this NFT + */ + TokenNftInfo nft = 2; } diff --git a/services/token_get_nft_infos.proto b/services/token_get_nft_infos.proto index 7b016443..07a74254 100644 --- a/services/token_get_nft_infos.proto +++ b/services/token_get_nft_infos.proto @@ -30,28 +30,62 @@ import "token_get_nft_info.proto"; import "query_header.proto"; import "response_header.proto"; -/* Applicable only to tokens of type NON_FUNGIBLE_UNIQUE. Gets info on NFTs N through M on the list of NFTs associated with a given NON_FUNGIBLE_UNIQUE Token. - * Example: If there are 10 NFTs issued, having start=0 and end=5 will query for the first 5 NFTs. Querying +all 10 NFTs will require start=0 and end=10 +/** + * Applicable only to tokens of type NON_FUNGIBLE_UNIQUE. Gets info on NFTs N through M on the list + * of NFTs associated with a given NON_FUNGIBLE_UNIQUE Token. + * Example: If there are 10 NFTs issued, having start=0 and end=5 will query for the first 5 NFTs. + * Querying +all 10 NFTs will require start=0 and end=10 * * INVALID_QUERY_RANGE response code will be returned if: * 1) Start > End * 2) Start and End indices are non-positive * 3) Start and End indices are out of boundaries for the retrieved nft list - * 4) The range between Start and End is bigger than the global dynamic property for maximum query range + * 4) The range between Start and End is bigger than the global dynamic property for maximum query + * range * * NOT_SUPPORTED response code will be returned if the queried token is of type FUNGIBLE_COMMON * * INVALID_TOKEN_ID response code will be returned if the queried token does not exist */ message TokenGetNftInfosQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - TokenID tokenID = 2; // The ID of the token for which information is requested - int64 start = 3; // Specifies the start index (inclusive) of the range of NFTs to query for. Value must be in the range [0; ownedNFTs-1] - int64 end = 4; // Specifies the end index (exclusive) of the range of NFTs to query for. Value must be in the range (start; ownedNFTs] + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The ID of the token for which information is requested + */ + TokenID tokenID = 2; + + /** + * Specifies the start index (inclusive) of the range of NFTs to query for. Value must be in the + * range [0; ownedNFTs-1] + */ + int64 start = 3; + + /** + * Specifies the end index (exclusive) of the range of NFTs to query for. Value must be in the + * range (start; ownedNFTs] + */ + int64 end = 4; } message TokenGetNftInfosResponse { - ResponseHeader header = 1; // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - TokenID tokenID = 2; // The Token with type NON_FUNGIBLE that this record is for - repeated TokenNftInfo nfts = 3; // List of NFTs associated to the specified token + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + + /** + * The Token with type NON_FUNGIBLE that this record is for + */ + TokenID tokenID = 2; + + /** + * List of NFTs associated to the specified token + */ + repeated TokenNftInfo nfts = 3; } diff --git a/services/token_grant_kyc.proto b/services/token_grant_kyc.proto index b5b1bb60..de4dd4b1 100644 --- a/services/token_grant_kyc.proto +++ b/services/token_grant_kyc.proto @@ -27,16 +27,26 @@ option java_multiple_files = true; import "basic_types.proto"; -/* Grants KYC to the account for the given token. Must be signed by the Token's kycKey. - If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. - If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. - If the provided token is not found, the transaction will resolve to INVALID_TOKEN_ID. - If the provided token has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. - If an Association between the provided token and account is not found, the transaction will resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. - If no KYC Key is defined, the transaction will resolve to TOKEN_HAS_NO_KYC_KEY. - Once executed the Account is marked as KYC Granted. +/** + * Grants KYC to the account for the given token. Must be signed by the Token's kycKey. + * If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. + * If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. + * If the provided token is not found, the transaction will resolve to INVALID_TOKEN_ID. + * If the provided token has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. + * If an Association between the provided token and account is not found, the transaction will + * resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. + * If no KYC Key is defined, the transaction will resolve to TOKEN_HAS_NO_KYC_KEY. + * Once executed the Account is marked as KYC Granted. */ message TokenGrantKycTransactionBody { - TokenID token = 1; // The token for which this account will be granted KYC. If token does not exist, transaction results in INVALID_TOKEN_ID - AccountID account = 2; // The account to be KYCed + /** + * The token for which this account will be granted KYC. If token does not exist, transaction + * results in INVALID_TOKEN_ID + */ + TokenID token = 1; + + /** + * The account to be KYCed + */ + AccountID account = 2; } diff --git a/services/token_mint.proto b/services/token_mint.proto index dad909ff..c2091b67 100644 --- a/services/token_mint.proto +++ b/services/token_mint.proto @@ -27,18 +27,40 @@ option java_multiple_files = true; import "basic_types.proto"; -/* -Mints tokens to the Token's treasury Account. If no Supply Key is defined, the transaction will resolve to TOKEN_HAS_NO_SUPPLY_KEY. -The operation increases the Total Supply of the Token. The maximum total supply a token can have is 2^63-1. -The amount provided must be in the lowest denomination possible. Example: -Token A has 2 decimals. In order to mint 100 tokens, one must provide amount of 10000. In order to mint 100.55 tokens, one must provide amount of 10055. -If both amount and metadata list get filled, a INVALID_TRANSACTION_BODY response code will be returned. -If the metadata list contains metadata which is too large, a METADATA_TOO_LONG response code will be returned. -If neither the amount nor the metadata list get filled, a INVALID_TOKEN_MINT_AMOUNT response code will be returned. -If the metadata list count is greater than the batch size limit global dynamic property, a BATCH_SIZE_LIMIT_EXCEEDED response code will be returned. +/** + * Mints tokens to the Token's treasury Account. If no Supply Key is defined, the transaction will + * resolve to TOKEN_HAS_NO_SUPPLY_KEY. + * The operation increases the Total Supply of the Token. The maximum total supply a token can have + * is 2^63-1. + * The amount provided must be in the lowest denomination possible. Example: + * Token A has 2 decimals. In order to mint 100 tokens, one must provide amount of 10000. In order + * to mint 100.55 tokens, one must provide amount of 10055. + * If both amount and metadata list get filled, a INVALID_TRANSACTION_BODY response code will be + * returned. + * If the metadata list contains metadata which is too large, a METADATA_TOO_LONG response code will + * be returned. + * If neither the amount nor the metadata list get filled, a INVALID_TOKEN_MINT_AMOUNT response code + * will be returned. + * If the metadata list count is greater than the batch size limit global dynamic property, a + * BATCH_SIZE_LIMIT_EXCEEDED response code will be returned. */ message TokenMintTransactionBody { - TokenID token = 1; // The token for which to mint tokens. If token does not exist, transaction results in INVALID_TOKEN_ID - uint64 amount = 2; // Applicable to tokens of type FUNGIBLE_COMMON. The amount to mint to the Treasury Account. Amount must be a positive non-zero number represented in the lowest denomination of the token. The new supply must be lower than 2^63. - repeated bytes metadata = 3; // Applicable to tokens of type NON_FUNGIBLE_UNIQUE. A list of metadata that are being created. Maximum allowed size of each metadata is 100 bytes + /** + * The token for which to mint tokens. If token does not exist, transaction results in + * INVALID_TOKEN_ID + */ + TokenID token = 1; + + /** + * Applicable to tokens of type FUNGIBLE_COMMON. The amount to mint to the Treasury Account. + * Amount must be a positive non-zero number represented in the lowest denomination of the + * token. The new supply must be lower than 2^63. + */ + uint64 amount = 2; + + /** + * Applicable to tokens of type NON_FUNGIBLE_UNIQUE. A list of metadata that are being created. + * Maximum allowed size of each metadata is 100 bytes + */ + repeated bytes metadata = 3; } diff --git a/services/token_revoke_kyc.proto b/services/token_revoke_kyc.proto index 0dca9f69..61a120a4 100644 --- a/services/token_revoke_kyc.proto +++ b/services/token_revoke_kyc.proto @@ -27,16 +27,26 @@ option java_multiple_files = true; import "basic_types.proto"; -/* Revokes KYC to the account for the given token. Must be signed by the Token's kycKey. - If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. - If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. - If the provided token is not found, the transaction will resolve to INVALID_TOKEN_ID. - If the provided token has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. - If an Association between the provided token and account is not found, the transaction will resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. - If no KYC Key is defined, the transaction will resolve to TOKEN_HAS_NO_KYC_KEY. - Once executed the Account is marked as KYC Revoked +/** + * Revokes KYC to the account for the given token. Must be signed by the Token's kycKey. + * If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. + * If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. + * If the provided token is not found, the transaction will resolve to INVALID_TOKEN_ID. + * If the provided token has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. + * If an Association between the provided token and account is not found, the transaction will + * resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. + * If no KYC Key is defined, the transaction will resolve to TOKEN_HAS_NO_KYC_KEY. + * Once executed the Account is marked as KYC Revoked */ message TokenRevokeKycTransactionBody { - TokenID token = 1; // The token for which this account will get his KYC revoked. If token does not exist, transaction results in INVALID_TOKEN_ID - AccountID account = 2; // The account to be KYC Revoked + /** + * The token for which this account will get his KYC revoked. If token does not exist, + * transaction results in INVALID_TOKEN_ID + */ + TokenID token = 1; + + /** + * The account to be KYC Revoked + */ + AccountID account = 2; } diff --git a/services/token_service.proto b/services/token_service.proto index 42e46845..fc79c3f9 100644 --- a/services/token_service.proto +++ b/services/token_service.proto @@ -29,41 +29,92 @@ import "response.proto"; import "transaction_response.proto"; import "transaction.proto"; -/* Transactions and queries for the Token Service */ +/** + * Transactions and queries for the Token Service + */ service TokenService { - // Creates a new Token by submitting the transaction + /** + * Creates a new Token by submitting the transaction + */ rpc createToken (Transaction) returns (TransactionResponse); - // Updates the account by submitting the transaction + + /** + * Updates the account by submitting the transaction + */ rpc updateToken (Transaction) returns (TransactionResponse); - // Mints an amount of the token to the defined treasury account + + /** + * Mints an amount of the token to the defined treasury account + */ rpc mintToken (Transaction) returns (TransactionResponse); - // Burns an amount of the token from the defined treasury account + + /** + * Burns an amount of the token from the defined treasury account + */ rpc burnToken (Transaction) returns (TransactionResponse); - // Deletes a Token + + /** + * Deletes a Token + */ rpc deleteToken (Transaction) returns (TransactionResponse); - // Wipes the provided amount of tokens from the specified Account ID + + /** + * Wipes the provided amount of tokens from the specified Account ID + */ rpc wipeTokenAccount (Transaction) returns (TransactionResponse); - // Freezes the transfer of tokens to or from the specified Account ID + + /** + * Freezes the transfer of tokens to or from the specified Account ID + */ rpc freezeTokenAccount (Transaction) returns (TransactionResponse); - // Unfreezes the transfer of tokens to or from the specified Account ID + + /** + * Unfreezes the transfer of tokens to or from the specified Account ID + */ rpc unfreezeTokenAccount (Transaction) returns (TransactionResponse); - // Flags the provided Account ID as having gone through KYC + + /** + * Flags the provided Account ID as having gone through KYC + */ rpc grantKycToTokenAccount (Transaction) returns (TransactionResponse); - // Removes the KYC flag of the provided Account ID + + /** + * Removes the KYC flag of the provided Account ID + */ rpc revokeKycFromTokenAccount (Transaction) returns (TransactionResponse); - // Associates tokens to an account + + /** + * Associates tokens to an account + */ rpc associateTokens (Transaction) returns (TransactionResponse); - // Dissociates tokens from an account + + /** + * Dissociates tokens from an account + */ rpc dissociateTokens (Transaction) returns (TransactionResponse); - // Updates the custom fee schedule on a token + + /** + * Updates the custom fee schedule on a token + */ rpc updateTokenFeeSchedule (Transaction) returns (TransactionResponse); - // Retrieves the metadata of a token + /** + * Retrieves the metadata of a token + */ rpc getTokenInfo (Query) returns (Response); - // Gets info on NFTs N through M on the list of NFTs associated with a given account + + /** + * Gets info on NFTs N through M on the list of NFTs associated with a given account + */ rpc getAccountNftInfos (Query) returns (Response); - // Retrieves the metadata of an NFT by TokenID and serial number + + /** + * Retrieves the metadata of an NFT by TokenID and serial number + */ rpc getTokenNftInfo (Query) returns (Response); - // Gets info on NFTs N through M on the list of NFTs associated with a given Token of type NON_FUNGIBLE + + /** + * Gets info on NFTs N through M on the list of NFTs associated with a given Token of type NON_FUNGIBLE + */ rpc getTokenNftInfos (Query) returns (Response); } diff --git a/services/token_unfreeze_account.proto b/services/token_unfreeze_account.proto index 15735e93..32d48600 100644 --- a/services/token_unfreeze_account.proto +++ b/services/token_unfreeze_account.proto @@ -27,16 +27,28 @@ option java_multiple_files = true; import "basic_types.proto"; -/* Unfreezes transfers of the specified token for the account. Must be signed by the Token's freezeKey. - If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. - If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. - If the provided token is not found, the transaction will resolve to INVALID_TOKEN_ID. - If the provided token has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. - If an Association between the provided token and account is not found, the transaction will resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. - If no Freeze Key is defined, the transaction will resolve to TOKEN_HAS_NO_FREEZE_KEY. - Once executed the Account is marked as Unfrozen and will be able to receive or send tokens. The operation is idempotent. +/** + * Unfreezes transfers of the specified token for the account. Must be signed by the Token's + * freezeKey. + * If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. + * If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. + * If the provided token is not found, the transaction will resolve to INVALID_TOKEN_ID. + * If the provided token has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. + * If an Association between the provided token and account is not found, the transaction will + * resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. + * If no Freeze Key is defined, the transaction will resolve to TOKEN_HAS_NO_FREEZE_KEY. + * Once executed the Account is marked as Unfrozen and will be able to receive or send tokens. The + * operation is idempotent. */ message TokenUnfreezeAccountTransactionBody { - TokenID token = 1; // The token for which this account will be unfrozen. If token does not exist, transaction results in INVALID_TOKEN_ID - AccountID account = 2; // The account to be unfrozen + /** + * The token for which this account will be unfrozen. If token does not exist, transaction + * results in INVALID_TOKEN_ID + */ + TokenID token = 1; + + /** + * The account to be unfrozen + */ + AccountID account = 2; } diff --git a/services/token_update.proto b/services/token_update.proto index 70bb38bf..6cfc75ca 100644 --- a/services/token_update.proto +++ b/services/token_update.proto @@ -30,32 +30,109 @@ import "duration.proto"; import "timestamp.proto"; import "google/protobuf/wrappers.proto"; -/* At consensus, updates an already created token to the given values. +/** + * At consensus, updates an already created token to the given values. + * + * If no value is given for a field, that field is left unchanged. For an immutable tokens (that is, + * a token without an admin key), only the expiry may be updated. Setting any other field in that + * case will cause the transaction status to resolve to TOKEN_IS_IMMUTABLE. + * + * --- Signing Requirements --- + * 1. Whether or not a token has an admin key, its expiry can be extended with only the transaction + * payer's signature. + * 2. Updating any other field of a mutable token requires the admin key's signature. + * 3. If a new admin key is set, this new key must sign unless it is exactly an empty + * KeyList. This special sentinel key removes the existing admin key and causes the + * token to become immutable. (Other Key structures without a constituent + * Ed25519 key will be rejected with INVALID_ADMIN_KEY.) + * 4. If a new treasury is set, the new treasury account's key must sign the transaction. + * + * --- Nft Requirements --- + * 1. If a non fungible token has a positive treasury balance, the operation will abort with + * CURRENT_TREASURY_STILL_OWNS_NFTS. + */ +message TokenUpdateTransactionBody { + /** + * The Token to be updated + */ + TokenID token = 1; -If no value is given for a field, that field is left unchanged. For an immutable tokens (that is, a token without an admin key), only the expiry may be updated. Setting any other field in that case will cause the transaction status to resolve to TOKEN_IS_IMMUTABLE. + /** + * The new publicly visible Token symbol, limited to a UTF-8 encoding of length + * tokens.maxTokenNameUtf8Bytes. + */ + string symbol = 2; ---- Signing Requirements --- -1. Whether or not a token has an admin key, its expiry can be extended with only the transaction payer's signature. -2. Updating any other field of a mutable token requires the admin key's signature. -3. If a new admin key is set, this new key must sign unless it is exactly an empty KeyList. This special sentinel key removes the existing admin key and causes the token to become immutable. (Other Key structures without a constituent Ed25519 key will be rejected with INVALID_ADMIN_KEY.) -4. If a new treasury is set, the new treasury account's key must sign the transaction. + /** + * The new publicly visible name of the Token, limited to a UTF-8 encoding of length + * tokens.maxSymbolUtf8Bytes. + */ + string name = 3; ---- Nft Requirements --- -1. If a non fungible token has a positive treasury balance, the operation will abort with CURRENT_TREASURY_STILL_OWNS_NFTS. -*/ -message TokenUpdateTransactionBody { - TokenID token = 1; // The Token to be updated - string symbol = 2; // The new publicly visible Token symbol, limited to a UTF-8 encoding of length tokens.maxTokenNameUtf8Bytes. - string name = 3; // The new publicly visible name of the Token, limited to a UTF-8 encoding of length tokens.maxSymbolUtf8Bytes. - AccountID treasury = 4; // The new Treasury account of the Token. If the provided treasury account is not existing or deleted, the response will be INVALID_TREASURY_ACCOUNT_FOR_TOKEN. If successful, the Token balance held in the previous Treasury Account is transferred to the new one. - Key adminKey = 5; // The new admin key of the Token. If Token is immutable, transaction will resolve to TOKEN_IS_IMMUTABlE. - Key kycKey = 6; // The new KYC key of the Token. If Token does not have currently a KYC key, transaction will resolve to TOKEN_HAS_NO_KYC_KEY. - Key freezeKey = 7; // The new Freeze key of the Token. If the Token does not have currently a Freeze key, transaction will resolve to TOKEN_HAS_NO_FREEZE_KEY. - Key wipeKey = 8; // The new Wipe key of the Token. If the Token does not have currently a Wipe key, transaction will resolve to TOKEN_HAS_NO_WIPE_KEY. - Key supplyKey = 9; // The new Supply key of the Token. If the Token does not have currently a Supply key, transaction will resolve to TOKEN_HAS_NO_SUPPLY_KEY. - AccountID autoRenewAccount = 10; // The new account which will be automatically charged to renew the token's expiration, at autoRenewPeriod interval. - Duration autoRenewPeriod = 11; // The new interval at which the auto-renew account will be charged to extend the token's expiry. - Timestamp expiry = 12; // The new expiry time of the token. Expiry can be updated even if admin key is not set. If the provided expiry is earlier than the current token expiry, transaction wil resolve to INVALID_EXPIRATION_TIME - google.protobuf.StringValue memo = 13; // If set, the new memo to be associated with the token (UTF-8 encoding max 100 bytes) - Key fee_schedule_key = 14; // If set, the new key to use to update the token's custom fee schedule; if the token does not currently have this key, transaction will resolve to TOKEN_HAS_NO_FEE_SCHEDULE_KEY + /** + * The new Treasury account of the Token. If the provided treasury account is not existing or + * deleted, the response will be INVALID_TREASURY_ACCOUNT_FOR_TOKEN. If successful, the Token + * balance held in the previous Treasury Account is transferred to the new one. + */ + AccountID treasury = 4; + + /** + * The new admin key of the Token. If Token is immutable, transaction will resolve to + * TOKEN_IS_IMMUTABlE. + */ + Key adminKey = 5; + + /** + * The new KYC key of the Token. If Token does not have currently a KYC key, transaction will + * resolve to TOKEN_HAS_NO_KYC_KEY. + */ + Key kycKey = 6; + + /** + * The new Freeze key of the Token. If the Token does not have currently a Freeze key, + * transaction will resolve to TOKEN_HAS_NO_FREEZE_KEY. + */ + Key freezeKey = 7; + + /** + * The new Wipe key of the Token. If the Token does not have currently a Wipe key, transaction + * will resolve to TOKEN_HAS_NO_WIPE_KEY. + */ + Key wipeKey = 8; + + /** + * The new Supply key of the Token. If the Token does not have currently a Supply key, + * transaction will resolve to TOKEN_HAS_NO_SUPPLY_KEY. + */ + Key supplyKey = 9; + + /** + * The new account which will be automatically charged to renew the token's expiration, at + * autoRenewPeriod interval. + */ + AccountID autoRenewAccount = 10; + + /** + * The new interval at which the auto-renew account will be charged to extend the token's + * expiry. + */ + Duration autoRenewPeriod = 11; + + /** + * The new expiry time of the token. Expiry can be updated even if admin key is not set. If the + * provided expiry is earlier than the current token expiry, transaction wil resolve to + * INVALID_EXPIRATION_TIME + */ + Timestamp expiry = 12; + + /** + * If set, the new memo to be associated with the token (UTF-8 encoding max 100 bytes) + */ + google.protobuf.StringValue memo = 13; + + /** + * If set, the new key to use to update the token's custom fee schedule; if the token does not + * currently have this key, transaction will resolve to TOKEN_HAS_NO_FEE_SCHEDULE_KEY + */ + Key fee_schedule_key = 14; } diff --git a/services/token_wipe_account.proto b/services/token_wipe_account.proto index 03f349a1..357b1fdb 100644 --- a/services/token_wipe_account.proto +++ b/services/token_wipe_account.proto @@ -27,27 +27,55 @@ option java_multiple_files = true; import "basic_types.proto"; -/* Wipes the provided amount of tokens from the specified Account. Must be signed by the Token's Wipe key. - If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. - If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. - If the provided token is not found, the transaction will resolve to INVALID_TOKEN_ID. - If the provided token has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. - If an Association between the provided token and account is not found, the transaction will resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. - If Wipe Key is not present in the Token, transaction results in TOKEN_HAS_NO_WIPE_KEY. - If the provided account is the Token's Treasury Account, transaction results in CANNOT_WIPE_TOKEN_TREASURY_ACCOUNT - On success, tokens are removed from the account and the total supply of the token is decreased by the wiped amount. - - If both amount and serialNumbers get filled, a INVALID_TRANSACTION_BODY response code will be returned. - If neither the amount nor the serialNumbers get filled, a INVALID_WIPING_AMOUNT response code will be returned. - If the serialNumbers list contains a non-positive integer as a serial number, a INVALID_NFT_ID response code will be returned. - If the serialNumbers' list count is greater than the batch size limit global dynamic property, a BATCH_SIZE_LIMIT_EXCEEDED response code will be returned. - - The amount provided is in the lowest denomination possible. Example: - Token A has 2 decimals. In order to wipe 100 tokens from account, one must provide amount of 10000. In order to wipe 100.55 tokens, one must provide amount of 10055. +/** + * Wipes the provided amount of tokens from the specified Account. Must be signed by the Token's + * Wipe key. + * If the provided account is not found, the transaction will resolve to INVALID_ACCOUNT_ID. + * If the provided account has been deleted, the transaction will resolve to ACCOUNT_DELETED. + * If the provided token is not found, the transaction will resolve to INVALID_TOKEN_ID. + * If the provided token has been deleted, the transaction will resolve to TOKEN_WAS_DELETED. + * If an Association between the provided token and account is not found, the transaction will + * resolve to TOKEN_NOT_ASSOCIATED_TO_ACCOUNT. + * If Wipe Key is not present in the Token, transaction results in TOKEN_HAS_NO_WIPE_KEY. + * If the provided account is the Token's Treasury Account, transaction results in + * CANNOT_WIPE_TOKEN_TREASURY_ACCOUNT + * On success, tokens are removed from the account and the total supply of the token is decreased by + * the wiped amount. + * + * If both amount and serialNumbers get filled, a INVALID_TRANSACTION_BODY response code will be + * returned. + * If neither the amount nor the serialNumbers get filled, a INVALID_WIPING_AMOUNT response code + * will be returned. + * If the serialNumbers list contains a non-positive integer as a serial number, a INVALID_NFT_ID + * response code will be returned. + * If the serialNumbers' list count is greater than the batch size limit global dynamic property, a + * BATCH_SIZE_LIMIT_EXCEEDED response code will be returned. + * + * The amount provided is in the lowest denomination possible. Example: + * Token A has 2 decimals. In order to wipe 100 tokens from account, one must provide amount of + * 10000. In order to wipe 100.55 tokens, one must provide amount of 10055. */ message TokenWipeAccountTransactionBody { - TokenID token = 1; // The token for which the account will be wiped. If token does not exist, transaction results in INVALID_TOKEN_ID - AccountID account = 2; // The account to be wiped - uint64 amount = 3; // Applicable to tokens of type FUNGIBLE_COMMON. The amount of tokens to wipe from the specified account. Amount must be a positive non-zero number in the lowest denomination possible, not bigger than the token balance of the account (0; balance] - repeated int64 serialNumbers = 4; // Applicable to tokens of type NON_FUNGIBLE_UNIQUE. The list of serial numbers to be wiped. + /** + * The token for which the account will be wiped. If token does not exist, transaction results + * in INVALID_TOKEN_ID + */ + TokenID token = 1; + + /** + * The account to be wiped + */ + AccountID account = 2; + + /** + * Applicable to tokens of type FUNGIBLE_COMMON. The amount of tokens to wipe from the specified + * account. Amount must be a positive non-zero number in the lowest denomination possible, not + * bigger than the token balance of the account (0; balance] + */ + uint64 amount = 3; + + /** + * Applicable to tokens of type NON_FUNGIBLE_UNIQUE. The list of serial numbers to be wiped. + */ + repeated int64 serialNumbers = 4; } diff --git a/services/transaction.proto b/services/transaction.proto index f6c06aa6..e4fd6983 100644 --- a/services/transaction.proto +++ b/services/transaction.proto @@ -30,17 +30,39 @@ import "duration.proto"; import "basic_types.proto"; import "transaction_body.proto"; -/* A single signed transaction, including all its signatures. The SignatureList will have a Signature for each Key in the transaction, either explicit or implicit, in the order that they appear in the transaction. For example, a CryptoTransfer will first have a Signature corresponding to the Key for the paying account, followed by a Signature corresponding to the Key for each account that is sending or receiving cryptocurrency in the transfer. Each Transaction should not have more than 50 levels. +/** + * A single signed transaction, including all its signatures. The SignatureList will have a + * Signature for each Key in the transaction, either explicit or implicit, in the order that they + * appear in the transaction. For example, a CryptoTransfer will first have a Signature + * corresponding to the Key for the paying account, followed by a Signature corresponding to the Key + * for each account that is sending or receiving cryptocurrency in the transfer. Each Transaction + * should not have more than 50 levels. * The SignatureList field is deprecated and succeeded by SignatureMap. */ message Transaction { - TransactionBody body = 1 [deprecated = true]; // the body of the transaction, which needs to be signed - - SignatureList sigs = 2 [deprecated = true]; // The signatures on the body, to authorize the transaction; deprecated and to be succeeded by SignatureMap field + /** + * the body of the transaction, which needs to be signed + */ + TransactionBody body = 1 [deprecated = true]; + + /** + * The signatures on the body, to authorize the transaction; deprecated and to be succeeded by + * SignatureMap field + */ + SignatureList sigs = 2 [deprecated = true]; - SignatureMap sigMap = 3 [deprecated = true]; // The signatures on the body with the new format, to authorize the transaction + /** + * The signatures on the body with the new format, to authorize the transaction + */ + SignatureMap sigMap = 3 [deprecated = true]; - bytes bodyBytes = 4 [deprecated = true]; // TransactionBody serialized into bytes, which needs to be signed + /** + * TransactionBody serialized into bytes, which needs to be signed + */ + bytes bodyBytes = 4 [deprecated = true]; - bytes signedTransactionBytes = 5; // SignedTransaction serialized into bytes + /** + * SignedTransaction serialized into bytes + */ + bytes signedTransactionBytes = 5; } diff --git a/services/transaction_body.proto b/services/transaction_body.proto index 68ffee68..8fde2e60 100644 --- a/services/transaction_body.proto +++ b/services/transaction_body.proto @@ -74,58 +74,233 @@ import "schedule_create.proto"; import "schedule_delete.proto"; import "schedule_sign.proto"; -/* A single transaction. All transaction types are possible here. */ +/** + * A single transaction. All transaction types are possible here. + */ message TransactionBody { - TransactionID transactionID = 1; // The ID for this transaction, which includes the payer's account (the account paying the transaction fee). If two transactions have the same transactionID, they won't both have an effect - AccountID nodeAccountID = 2; // The account of the node that submits the client's transaction to the network - uint64 transactionFee = 3; // The maximum transaction fee the client is willing to pay - Duration transactionValidDuration = 4; //The transaction is invalid if consensusTimestamp > transactionID.transactionValidStart + transactionValidDuration - bool generateRecord = 5 [deprecated = true]; // Should a record of this transaction be generated? (A receipt is always generated, but the record is optional) - string memo = 6; // Any notes or descriptions that should be put into the record (max length 100) + /** + * The ID for this transaction, which includes the payer's account (the account paying the + * transaction fee). If two transactions have the same transactionID, they won't both have an + * effect + */ + TransactionID transactionID = 1; + + /** + * The account of the node that submits the client's transaction to the network + */ + AccountID nodeAccountID = 2; + + /** + * The maximum transaction fee the client is willing to pay + */ + uint64 transactionFee = 3; + + /** + * The transaction is invalid if consensusTimestamp > transactionID.transactionValidStart + + * transactionValidDuration + */ + Duration transactionValidDuration = 4; + + /** + * Should a record of this transaction be generated? (A receipt is always generated, but the + * record is optional) + */ + bool generateRecord = 5 [deprecated = true]; + + /** + * Any notes or descriptions that should be put into the record (max length 100) + */ + string memo = 6; + oneof data { - ContractCallTransactionBody contractCall = 7; // Calls a function of a contract instance - ContractCreateTransactionBody contractCreateInstance = 8; // Creates a contract instance - ContractUpdateTransactionBody contractUpdateInstance = 9; // Updates a contract - ContractDeleteTransactionBody contractDeleteInstance = 22; //Delete contract and transfer remaining balance into specified account - - CryptoAddLiveHashTransactionBody cryptoAddLiveHash = 10; // Attach a new livehash to an account - CryptoCreateTransactionBody cryptoCreateAccount = 11; // Create a new cryptocurrency account - CryptoDeleteTransactionBody cryptoDelete = 12; // Delete a cryptocurrency account (mark as deleted, and transfer hbars out) - CryptoDeleteLiveHashTransactionBody cryptoDeleteLiveHash = 13; // Remove a livehash from an account - CryptoTransferTransactionBody cryptoTransfer = 14; // Transfer amount between accounts - CryptoUpdateTransactionBody cryptoUpdateAccount = 15; // Modify information such as the expiration date for an account - - FileAppendTransactionBody fileAppend = 16; // Add bytes to the end of the contents of a file - FileCreateTransactionBody fileCreate = 17; // Create a new file - FileDeleteTransactionBody fileDelete = 18; // Delete a file (remove contents and mark as deleted until it expires) - FileUpdateTransactionBody fileUpdate = 19; // Modify information such as the expiration date for a file - SystemDeleteTransactionBody systemDelete = 20; // Hedera administrative deletion of a file or smart contract - SystemUndeleteTransactionBody systemUndelete = 21; //To undelete an entity deleted by SystemDelete - FreezeTransactionBody freeze = 23; // Freeze the nodes - - ConsensusCreateTopicTransactionBody consensusCreateTopic = 24; // Creates a topic - ConsensusUpdateTopicTransactionBody consensusUpdateTopic = 25; // Updates a topic - ConsensusDeleteTopicTransactionBody consensusDeleteTopic = 26; // Deletes a topic - ConsensusSubmitMessageTransactionBody consensusSubmitMessage = 27; // Submits message to a topic + /** + * Calls a function of a contract instance + */ + ContractCallTransactionBody contractCall = 7; + + /** + * Creates a contract instance + */ + ContractCreateTransactionBody contractCreateInstance = 8; + + /** + * Updates a contract + */ + ContractUpdateTransactionBody contractUpdateInstance = 9; + + /** + * Delete contract and transfer remaining balance into specified account + */ + ContractDeleteTransactionBody contractDeleteInstance = 22; + + /** + * Attach a new livehash to an account + */ + CryptoAddLiveHashTransactionBody cryptoAddLiveHash = 10; + + /** + * Create a new cryptocurrency account + */ + CryptoCreateTransactionBody cryptoCreateAccount = 11; + + /** + * Delete a cryptocurrency account (mark as deleted, and transfer hbars out) + */ + CryptoDeleteTransactionBody cryptoDelete = 12; + + /** + * Remove a livehash from an account + */ + CryptoDeleteLiveHashTransactionBody cryptoDeleteLiveHash = 13; + + /** + * Transfer amount between accounts + */ + CryptoTransferTransactionBody cryptoTransfer = 14; + + /** + * Modify information such as the expiration date for an account + */ + CryptoUpdateTransactionBody cryptoUpdateAccount = 15; + + /** + * Add bytes to the end of the contents of a file + */ + FileAppendTransactionBody fileAppend = 16; + + /** + * Create a new file + */ + FileCreateTransactionBody fileCreate = 17; + + /** + * Delete a file (remove contents and mark as deleted until it expires) + */ + FileDeleteTransactionBody fileDelete = 18; + + /** + * Modify information such as the expiration date for a file + */ + FileUpdateTransactionBody fileUpdate = 19; + + /** + * Hedera administrative deletion of a file or smart contract + */ + SystemDeleteTransactionBody systemDelete = 20; + /** + * To undelete an entity deleted by SystemDelete + */ + SystemUndeleteTransactionBody systemUndelete = 21; + + /** + * Freeze the nodes + */ + FreezeTransactionBody freeze = 23; + + /** + * Creates a topic + */ + ConsensusCreateTopicTransactionBody consensusCreateTopic = 24; + + /** + * Updates a topic + */ + ConsensusUpdateTopicTransactionBody consensusUpdateTopic = 25; + + /** + * Deletes a topic + */ + ConsensusDeleteTopicTransactionBody consensusDeleteTopic = 26; + + /** + * Submits message to a topic + */ + ConsensusSubmitMessageTransactionBody consensusSubmitMessage = 27; + + /** + * UNDOCUMENTED + */ UncheckedSubmitBody uncheckedSubmit = 28; - TokenCreateTransactionBody tokenCreation = 29; // Creates a token instance - TokenFreezeAccountTransactionBody tokenFreeze = 31; // Freezes account not to be able to transact with a token - TokenUnfreezeAccountTransactionBody tokenUnfreeze = 32; // Unfreezes account for a token - TokenGrantKycTransactionBody tokenGrantKyc = 33; // Grants KYC to an account for a token - TokenRevokeKycTransactionBody tokenRevokeKyc = 34; // Revokes KYC of an account for a token - TokenDeleteTransactionBody tokenDeletion = 35; // Deletes a token instance - TokenUpdateTransactionBody tokenUpdate = 36; // Updates a token instance - TokenMintTransactionBody tokenMint = 37; // Mints new tokens to a token's treasury account - TokenBurnTransactionBody tokenBurn = 38; // Burns tokens from a token's treasury account - TokenWipeAccountTransactionBody tokenWipe = 39; // Wipes amount of tokens from an account - TokenAssociateTransactionBody tokenAssociate = 40; // Associate tokens to an account - TokenDissociateTransactionBody tokenDissociate = 41; // Dissociate tokens from an account - TokenFeeScheduleUpdateTransactionBody token_fee_schedule_update = 45; // Updates a token's custom fee schedule - - ScheduleCreateTransactionBody scheduleCreate = 42; // Creates a schedule in the network's action queue - ScheduleDeleteTransactionBody scheduleDelete = 43; // Deletes a schedule from the network's action queue - ScheduleSignTransactionBody scheduleSign = 44; // Adds one or more Ed25519 keys to the affirmed signers of a scheduled transaction + /** + * Creates a token instance + */ + TokenCreateTransactionBody tokenCreation = 29; + + /** + * Freezes account not to be able to transact with a token + */ + TokenFreezeAccountTransactionBody tokenFreeze = 31; + + /** + * Unfreezes account for a token + */ + TokenUnfreezeAccountTransactionBody tokenUnfreeze = 32; + + /** + * Grants KYC to an account for a token + */ + TokenGrantKycTransactionBody tokenGrantKyc = 33; + + /** + * Revokes KYC of an account for a token + */ + TokenRevokeKycTransactionBody tokenRevokeKyc = 34; + + /** + * Deletes a token instance + */ + TokenDeleteTransactionBody tokenDeletion = 35; + + /** + * Updates a token instance + */ + TokenUpdateTransactionBody tokenUpdate = 36; + + /** + * Mints new tokens to a token's treasury account + */ + TokenMintTransactionBody tokenMint = 37; + + /** + * Burns tokens from a token's treasury account + */ + TokenBurnTransactionBody tokenBurn = 38; + + /** + * Wipes amount of tokens from an account + */ + TokenWipeAccountTransactionBody tokenWipe = 39; + + /** + * Associate tokens to an account + */ + TokenAssociateTransactionBody tokenAssociate = 40; + + /** + * Dissociate tokens from an account + */ + TokenDissociateTransactionBody tokenDissociate = 41; + + /** + * Updates a token's custom fee schedule + */ + TokenFeeScheduleUpdateTransactionBody token_fee_schedule_update = 45; + + /** + * Creates a schedule in the network's action queue + */ + ScheduleCreateTransactionBody scheduleCreate = 42; + + /** + * Deletes a schedule from the network's action queue + */ + ScheduleDeleteTransactionBody scheduleDelete = 43; + + /** + * Adds one or more Ed25519 keys to the affirmed signers of a scheduled transaction + */ + ScheduleSignTransactionBody scheduleSign = 44; } } diff --git a/services/transaction_contents.proto b/services/transaction_contents.proto index 6bb091f2..50e0c420 100644 --- a/services/transaction_contents.proto +++ b/services/transaction_contents.proto @@ -28,6 +28,13 @@ option java_multiple_files = true; import "basic_types.proto"; message SignedTransaction { - bytes bodyBytes = 1; // TransactionBody serialized into bytes, which needs to be signed - SignatureMap sigMap = 2; // The signatures on the body with the new format, to authorize the transaction + /** + * TransactionBody serialized into bytes, which needs to be signed + */ + bytes bodyBytes = 1; + + /** + * The signatures on the body with the new format, to authorize the transaction + */ + SignatureMap sigMap = 2; } diff --git a/services/transaction_get_fast_record.proto b/services/transaction_get_fast_record.proto index 5dcc0fea..fb75d8a2 100644 --- a/services/transaction_get_fast_record.proto +++ b/services/transaction_get_fast_record.proto @@ -30,13 +30,41 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* Get the tx record of a transaction, given its transaction ID. Once a transaction reaches consensus, then information about whether it succeeded or failed will be available until the end of the receipt period. Before and after the receipt period, and for a transaction that was never submitted, the receipt is unknown. This query is free (the payment field is left empty). */ +/** + * Get the tx record of a transaction, given its transaction ID. Once a transaction reaches + * consensus, then information about whether it succeeded or failed will be available until the end + * of the receipt period. Before and after the receipt period, and for a transaction that was never + * submitted, the receipt is unknown. This query is free (the payment field is left empty). + */ message TransactionGetFastRecordQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - TransactionID transactionID = 2; // The ID of the transaction for which the record is requested. + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The ID of the transaction for which the record is requested. + */ + TransactionID transactionID = 2; } -/* Response when the client sends the node TransactionGetFastRecordQuery. If it created a new entity (account, file, or smart contract instance) then one of the three ID fields will be filled in with the ID of the new entity. Sometimes a single transaction will create more than one new entity, such as when a new contract instance is created, and this also creates the new account that it owned by that instance. */ + +/** + * Response when the client sends the node TransactionGetFastRecordQuery. If it created a new entity + * (account, file, or smart contract instance) then one of the three ID fields will be filled in + * with the ID of the new entity. Sometimes a single transaction will create more than one new + * entity, such as when a new contract instance is created, and this also creates the new account + * that it owned by that instance. + */ message TransactionGetFastRecordResponse { - ResponseHeader header = 1; //Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - TransactionRecord transactionRecord = 2; // The requested transaction records + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + + /** + * The requested transaction records + */ + TransactionRecord transactionRecord = 2; } diff --git a/services/transaction_get_receipt.proto b/services/transaction_get_receipt.proto index 6a976825..e253558e 100644 --- a/services/transaction_get_receipt.proto +++ b/services/transaction_get_receipt.proto @@ -30,15 +30,59 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* Get the receipt of a transaction, given its transaction ID. Once a transaction reaches consensus, then information about whether it succeeded or failed will be available until the end of the receipt period. Before and after the receipt period, and for a transaction that was never submitted, the receipt is unknown. This query is free (the payment field is left empty). No State proof is available for this response*/ +/** + * Get the receipt of a transaction, given its transaction ID. Once a transaction reaches consensus, + * then information about whether it succeeded or failed will be available until the end of the + * receipt period. Before and after the receipt period, and for a transaction that was never + * submitted, the receipt is unknown. This query is free (the payment field is left empty). No + * State proof is available for this response + */ message TransactionGetReceiptQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - TransactionID transactionID = 2; // The ID of the transaction for which the receipt is requested. - bool includeDuplicates = 3; // Whether receipts of processing duplicate transactions should be returned along with the receipt of processing the first consensus transaction with the given id whose status was neither INVALID_NODE_ACCOUNT nor INVALID_PAYER_SIGNATURE; or, if no such receipt exists, the receipt of processing the first transaction to reach consensus with the given transaction id.. + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The ID of the transaction for which the receipt is requested. + */ + TransactionID transactionID = 2; + + /** + * Whether receipts of processing duplicate transactions should be returned along with the + * receipt of processing the first consensus transaction with the given id whose status was + * neither INVALID_NODE_ACCOUNT nor INVALID_PAYER_SIGNATURE; or, if no + * such receipt exists, the receipt of processing the first transaction to reach consensus with + * the given transaction id.. + */ + bool includeDuplicates = 3; } -/* Response when the client sends the node TransactionGetReceiptQuery. If it created a new entity (account, file, or smart contract instance) then one of the three ID fields will be filled in with the ID of the new entity. Sometimes a single transaction will create more than one new entity, such as when a new contract instance is created, and this also creates the new account that it owned by that instance. No State proof is available for this response */ +/** + * Response when the client sends the node TransactionGetReceiptQuery. If it created a new entity + * (account, file, or smart contract instance) then one of the three ID fields will be filled in + * with the ID of the new entity. Sometimes a single transaction will create more than one new + * entity, such as when a new contract instance is created, and this also creates the new account + * that it owned by that instance. No State proof is available for this response + */ message TransactionGetReceiptResponse { - ResponseHeader header = 1; //Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither - TransactionReceipt receipt = 2; // Either the receipt of processing the first consensus transaction with the given id whose status was neither INVALID_NODE_ACCOUNT nor INVALID_PAYER_SIGNATURE; or, if no such receipt exists, the receipt of processing the first transaction to reach consensus with the given transaction id. - repeated TransactionReceipt duplicateTransactionReceipts = 4; // The receipts of processing all consensus transaction with the same id as the distinguished receipt above, in chronological order. + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither + */ + ResponseHeader header = 1; + + /** + * Either the receipt of processing the first consensus transaction with the given id whose + * status was neither INVALID_NODE_ACCOUNT nor INVALID_PAYER_SIGNATURE; + * or, if no such receipt exists, the receipt of processing the first transaction to + * reach consensus with the given transaction id. + */ + TransactionReceipt receipt = 2; + + /** + * The receipts of processing all consensus transaction with the same id as the distinguished + * receipt above, in chronological order. + */ + repeated TransactionReceipt duplicateTransactionReceipts = 4; } diff --git a/services/transaction_get_record.proto b/services/transaction_get_record.proto index a25f5e46..0b3a096b 100644 --- a/services/transaction_get_record.proto +++ b/services/transaction_get_record.proto @@ -30,17 +30,59 @@ import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -/* Get the record for a transaction. If the transaction requested a record, then the record lasts for one hour, and a state proof is available for it. If the transaction created an account, file, or smart contract instance, then the record will contain the ID for what it created. If the transaction called a smart contract function, then the record contains the result of that call. If the transaction was a cryptocurrency transfer, then the record includes the TransferList which gives the details of that transfer. If the transaction didn't return anything that should be in the record, then the results field will be set to nothing. */ +/** + * Get the record for a transaction. If the transaction requested a record, then the record lasts + * for one hour, and a state proof is available for it. If the transaction created an account, file, + * or smart contract instance, then the record will contain the ID for what it created. If the + * transaction called a smart contract function, then the record contains the result of that call. + * If the transaction was a cryptocurrency transfer, then the record includes the TransferList which + * gives the details of that transfer. If the transaction didn't return anything that should be in + * the record, then the results field will be set to nothing. + */ message TransactionGetRecordQuery { - QueryHeader header = 1; // Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). - TransactionID transactionID = 2; // The ID of the transaction for which the record is requested. - bool includeDuplicates = 3; // Whether records of processing duplicate transactions should be returned along with the record of processing the first consensus transaction with the given id whose status was neither INVALID_NODE_ACCOUNT nor INVALID_PAYER_SIGNATURE; or, if no such record exists, the record of processing the first transaction to reach consensus with the given transaction id.. + /** + * Standard info sent from client to node, including the signed payment, and what kind of + * response is requested (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * The ID of the transaction for which the record is requested. + */ + TransactionID transactionID = 2; + + /** + * Whether records of processing duplicate transactions should be returned along with the record + * of processing the first consensus transaction with the given id whose status was neither + * INVALID_NODE_ACCOUNT nor INVALID_PAYER_SIGNATURE; or, if no such + * record exists, the record of processing the first transaction to reach consensus with the + * given transaction id.. + */ + bool includeDuplicates = 3; } -/* Response when the client sends the node TransactionGetRecordQuery */ +/** + * Response when the client sends the node TransactionGetRecordQuery + */ message TransactionGetRecordResponse { - ResponseHeader header = 1; // Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither. - TransactionRecord transactionRecord = 3; // Either the record of processing the first consensus transaction with the given id whose status was neither INVALID_NODE_ACCOUNT nor INVALID_PAYER_SIGNATURE; or, if no such record exists, the record of processing the first transaction to reach consensus with the given transaction id. - repeated TransactionRecord duplicateTransactionRecords = 4; // The records of processing all consensus transaction with the same id as the distinguished record above, in chronological order. + /** + * Standard response from node to client, including the requested fields: cost, or state proof, + * or both, or neither. + */ + ResponseHeader header = 1; + + /** + * Either the record of processing the first consensus transaction with the given id whose + * status was neither INVALID_NODE_ACCOUNT nor INVALID_PAYER_SIGNATURE; + * or, if no such record exists, the record of processing the first transaction to reach + * consensus with the given transaction id. + */ + TransactionRecord transactionRecord = 3; + + /** + * The records of processing all consensus transaction with the same id as the distinguished + * record above, in chronological order. + */ + repeated TransactionRecord duplicateTransactionRecords = 4; } diff --git a/services/transaction_receipt.proto b/services/transaction_receipt.proto index 467fe5b7..0a59e1d8 100644 --- a/services/transaction_receipt.proto +++ b/services/transaction_receipt.proto @@ -29,87 +29,138 @@ import "basic_types.proto"; import "response_code.proto"; import "exchange_rate.proto"; -/* -The summary of a transaction's result so far. If the transaction has not reached consensus, this result will be necessarily incomplete. +/** + * The summary of a transaction's result so far. If the transaction has not reached consensus, this + * result will be necessarily incomplete. */ message TransactionReceipt { - // The consensus status of the transaction; is UNKNOWN if consensus has not been reached, or if the - // associated transaction did not have a valid payer signature + /** + * The consensus status of the transaction; is UNKNOWN if consensus has not been reached, or if + * the associated transaction did not have a valid payer signature + */ ResponseCodeEnum status = 1; - // In the receipt of a CryptoCreate, the id of the newly created account + /** + * In the receipt of a CryptoCreate, the id of the newly created account + */ AccountID accountID = 2; - // In the receipt of a FileCreate, the id of the newly created file + + /** + * In the receipt of a FileCreate, the id of the newly created file + */ FileID fileID = 3; - // In the receipt of a ContractCreate, the id of the newly created contract + + /** + * In the receipt of a ContractCreate, the id of the newly created contract + */ ContractID contractID = 4; - // The exchange rates in effect when the transaction reached consensus + + /** + * The exchange rates in effect when the transaction reached consensus + */ ExchangeRateSet exchangeRate = 5; - // In the receipt of a ConsensusCreateTopic, the id of the newly created topic. + + /** + * In the receipt of a ConsensusCreateTopic, the id of the newly created topic. + */ TopicID topicID = 6; - // In the receipt of a ConsensusSubmitMessage, the new sequence number of the topic that received the message + /** + * In the receipt of a ConsensusSubmitMessage, the new sequence number of the topic that + * received the message + */ uint64 topicSequenceNumber = 7; - // In the receipt of a ConsensusSubmitMessage, the new running hash of the topic that received the message. - // This 48-byte field is the output of a particular SHA-384 digest whose input data are determined by the - // value of the topicRunningHashVersion below. The bytes of each uint64 or uint32 are to be in Big-Endian - // format. - // - // IF the topicRunningHashVersion is '0' or '1', then the input data to the SHA-384 digest are, in order: - // --- - // 1. The previous running hash of the topic (48 bytes) - // 2. The topic's shard (8 bytes) - // 3. The topic's realm (8 bytes) - // 4. The topic's number (8 bytes) - // 5. The number of seconds since the epoch before the ConsensusSubmitMessage reached consensus (8 bytes) - // 6. The number of nanoseconds since 5. before the ConsensusSubmitMessage reached consensus (4 bytes) - // 7. The topicSequenceNumber from above (8 bytes) - // 8. The message bytes from the ConsensusSubmitMessage (variable). - // - // IF the topicRunningHashVersion is '2', then the input data to the SHA-384 digest are, in order: - // --- - // 1. The previous running hash of the topic (48 bytes) - // 2. The topicRunningHashVersion below (8 bytes) - // 3. The topic's shard (8 bytes) - // 4. The topic's realm (8 bytes) - // 5. The topic's number (8 bytes) - // 6. The number of seconds since the epoch before the ConsensusSubmitMessage reached consensus (8 bytes) - // 7. The number of nanoseconds since 6. before the ConsensusSubmitMessage reached consensus (4 bytes) - // 8. The topicSequenceNumber from above (8 bytes) - // 9. The output of the SHA-384 digest of the message bytes from the consensusSubmitMessage (48 bytes) - // - // Otherwise, IF the topicRunningHashVersion is '3', then the input data to the SHA-384 digest are, in order: - // --- - // 1. The previous running hash of the topic (48 bytes) - // 2. The topicRunningHashVersion below (8 bytes) - // 3. The payer account's shard (8 bytes) - // 4. The payer account's realm (8 bytes) - // 5. The payer account's number (8 bytes) - // 6. The topic's shard (8 bytes) - // 7. The topic's realm (8 bytes) - // 8. The topic's number (8 bytes) - // 9. The number of seconds since the epoch before the ConsensusSubmitMessage reached consensus (8 bytes) - // 10. The number of nanoseconds since 9. before the ConsensusSubmitMessage reached consensus (4 bytes) - // 11. The topicSequenceNumber from above (8 bytes) - // 12. The output of the SHA-384 digest of the message bytes from the consensusSubmitMessage (48 bytes) + /** + * In the receipt of a ConsensusSubmitMessage, the new running hash of the topic that received + * the message. This 48-byte field is the output of a particular SHA-384 digest whose input + * data are determined by the value of the topicRunningHashVersion below. The bytes of each + * uint64 or uint32 are to be in Big-Endian format. + * + * IF the topicRunningHashVersion is '0' or '1', then the input data to the SHA-384 digest are, + * in order: + * --- + * 1. The previous running hash of the topic (48 bytes) + * 2. The topic's shard (8 bytes) + * 3. The topic's realm (8 bytes) + * 4. The topic's number (8 bytes) + * 5. The number of seconds since the epoch before the ConsensusSubmitMessage reached + * consensus (8 bytes) + * 6. The number of nanoseconds since 5. before the ConsensusSubmitMessage reached + * consensus (4 bytes) + * 7. The topicSequenceNumber from above (8 bytes) + * 8. The message bytes from the ConsensusSubmitMessage (variable). + * + * IF the topicRunningHashVersion is '2', then the input data to the SHA-384 digest are, in + * order: + * --- + * 1. The previous running hash of the topic (48 bytes) + * 2. The topicRunningHashVersion below (8 bytes) + * 3. The topic's shard (8 bytes) + * 4. The topic's realm (8 bytes) + * 5. The topic's number (8 bytes) + * 6. The number of seconds since the epoch before the ConsensusSubmitMessage reached + * consensus (8 bytes) + * 7. The number of nanoseconds since 6. before the ConsensusSubmitMessage reached + * consensus (4 bytes) + * 8. The topicSequenceNumber from above (8 bytes) + * 9. The output of the SHA-384 digest of the message bytes from the + * consensusSubmitMessage (48 bytes) + * + * Otherwise, IF the topicRunningHashVersion is '3', then the input data to the SHA-384 digest + * are, in order: + * --- + * 1. The previous running hash of the topic (48 bytes) + * 2. The topicRunningHashVersion below (8 bytes) + * 3. The payer account's shard (8 bytes) + * 4. The payer account's realm (8 bytes) + * 5. The payer account's number (8 bytes) + * 6. The topic's shard (8 bytes) + * 7. The topic's realm (8 bytes) + * 8. The topic's number (8 bytes) + * 9. The number of seconds since the epoch before the ConsensusSubmitMessage reached + * consensus (8 bytes) + * 10. The number of nanoseconds since 9. before the ConsensusSubmitMessage reached + * consensus (4 bytes) + * 11. The topicSequenceNumber from above (8 bytes) + * 12. The output of the SHA-384 digest of the message bytes from the + * consensusSubmitMessage (48 bytes) + */ bytes topicRunningHash = 8; - // In the receipt of a ConsensusSubmitMessage, the version of the SHA-384 digest used to update the running hash. + /** + * In the receipt of a ConsensusSubmitMessage, the version of the SHA-384 digest used to update + * the running hash. + */ uint64 topicRunningHashVersion = 9; - // In the receipt of a CreateToken, the id of the newly created token + /** + * In the receipt of a CreateToken, the id of the newly created token + */ TokenID tokenID = 10; - // In the receipt of TokenMint, TokenWipe, TokenBurn, For fungible tokens - the current total supply of this token. For non fungible tokens - the total number of NFTs issued for a given tokenID + /** + * In the receipt of TokenMint, TokenWipe, TokenBurn, For fungible tokens - the current total + * supply of this token. For non fungible tokens - the total number of NFTs issued for a given + * tokenID + */ uint64 newTotalSupply = 11; - // In the receipt of a ScheduleCreate, the id of the newly created Scheduled Entity + /** + * In the receipt of a ScheduleCreate, the id of the newly created Scheduled Entity + */ ScheduleID scheduleID = 12; - // In the receipt of a ScheduleCreate or ScheduleSign that resolves to SUCCESS, the TransactionID that should be used to query for the receipt or record of the relevant scheduled transaction + /** + * In the receipt of a ScheduleCreate or ScheduleSign that resolves to SUCCESS, the + * TransactionID that should be used to query for the receipt or record of the relevant + * scheduled transaction + */ TransactionID scheduledTransactionID = 13; - // In the receipt of a TokenMint for tokens of type NON_FUNGIBLE_UNIQUE, the serial numbers of the newly created NFTs + /** + * In the receipt of a TokenMint for tokens of type NON_FUNGIBLE_UNIQUE, the serial numbers of + * the newly created NFTs + */ repeated int64 serialNumbers = 14; } diff --git a/services/transaction_record.proto b/services/transaction_record.proto index d99ae7da..fe19bac6 100644 --- a/services/transaction_record.proto +++ b/services/transaction_record.proto @@ -32,21 +32,82 @@ import "transaction_receipt.proto"; import "crypto_transfer.proto"; import "contract_call_local.proto"; -/* Response when the client sends the node TransactionGetRecordResponse */ +/** + * Response when the client sends the node TransactionGetRecordResponse + */ message TransactionRecord { - TransactionReceipt receipt = 1; // The status (reach consensus, or failed, or is unknown) and the ID of any new account/file/instance created. - bytes transactionHash = 2; // The hash of the Transaction that executed (not the hash of any Transaction that failed for having a duplicate TransactionID) - Timestamp consensusTimestamp = 3; // The consensus timestamp (or null if didn't reach consensus yet) - TransactionID transactionID = 4; // The ID of the transaction this record represents - string memo = 5; // The memo that was submitted as part of the transaction (max 100 bytes) - uint64 transactionFee = 6; // The actual transaction fee charged, not the original transactionFee value from TransactionBody + /** + * The status (reach consensus, or failed, or is unknown) and the ID of any new + * account/file/instance created. + */ + TransactionReceipt receipt = 1; + + /** + * The hash of the Transaction that executed (not the hash of any Transaction that failed for + * having a duplicate TransactionID) + */ + bytes transactionHash = 2; + + /** + * The consensus timestamp (or null if didn't reach consensus yet) + */ + Timestamp consensusTimestamp = 3; + + /** + * The ID of the transaction this record represents + */ + TransactionID transactionID = 4; + + /** + * The memo that was submitted as part of the transaction (max 100 bytes) + */ + string memo = 5; + + /** + * The actual transaction fee charged, not the original transactionFee value from + * TransactionBody + */ + uint64 transactionFee = 6; + oneof body { - ContractFunctionResult contractCallResult = 7; // Record of the value returned by the smart contract function (if it completed and didn't fail) from ContractCallTransaction - ContractFunctionResult contractCreateResult = 8; // Record of the value returned by the smart contract constructor (if it completed and didn't fail) from ContractCreateTransaction + /** + * Record of the value returned by the smart contract function (if it completed and didn't + * fail) from ContractCallTransaction + */ + ContractFunctionResult contractCallResult = 7; + + /** + * Record of the value returned by the smart contract constructor (if it completed and + * didn't fail) from ContractCreateTransaction + */ + ContractFunctionResult contractCreateResult = 8; } - TransferList transferList = 10; // All hbar transfers as a result of this transaction, such as fees, or transfers performed by the transaction, or by a smart contract it calls, or by the creation of threshold records that it triggers. - repeated TokenTransferList tokenTransferLists = 11; // All Token transfers as a result of this transaction - ScheduleID scheduleRef = 12; // Reference to the scheduled transaction ID that this transaction record represent - repeated AssessedCustomFee assessed_custom_fees = 13; // All custom fees that were assessed during a CryptoTransfer, and must be paid if the transaction status resolved to SUCCESS - repeated TokenAssociation automatic_token_associations = 14; // All token associations implicitly created while handling this transaction + + /** + * All hbar transfers as a result of this transaction, such as fees, or transfers performed by + * the transaction, or by a smart contract it calls, or by the creation of threshold records + * that it triggers. + */ + TransferList transferList = 10; + + /** + * All Token transfers as a result of this transaction + */ + repeated TokenTransferList tokenTransferLists = 11; + + /** + * Reference to the scheduled transaction ID that this transaction record represent + */ + ScheduleID scheduleRef = 12; + + /** + * All custom fees that were assessed during a CryptoTransfer, and must be paid if the + * transaction status resolved to SUCCESS + */ + repeated AssessedCustomFee assessed_custom_fees = 13; + + /** + * All token associations implicitly created while handling this transaction + */ + repeated TokenAssociation automatic_token_associations = 14; } diff --git a/services/transaction_response.proto b/services/transaction_response.proto index 491bfb48..38061cf3 100644 --- a/services/transaction_response.proto +++ b/services/transaction_response.proto @@ -28,8 +28,22 @@ option java_multiple_files = true; import "response_code.proto"; -/* When the client sends the node a transaction of any kind, the node replies with this, which simply says that the transaction passed the precheck (so the node will submit it to the network) or it failed (so it won't). If the fee offered was insufficient, this will also contain the amount of the required fee. To learn the consensus result, the client should later obtain a receipt (free), or can buy a more detailed record (not free). */ +/** + * When the client sends the node a transaction of any kind, the node replies with this, which + * simply says that the transaction passed the precheck (so the node will submit it to the network) + * or it failed (so it won't). If the fee offered was insufficient, this will also contain the + * amount of the required fee. To learn the consensus result, the client should later obtain a + * receipt (free), or can buy a more detailed record (not free). + */ message TransactionResponse { - ResponseCodeEnum nodeTransactionPrecheckCode = 1; // The response code that indicates the current status of the transaction. - uint64 cost = 2; // If the response code was INSUFFICIENT_TX_FEE, the actual transaction fee that would be required to execute the transaction. + /** + * The response code that indicates the current status of the transaction. + */ + ResponseCodeEnum nodeTransactionPrecheckCode = 1; + + /** + * If the response code was INSUFFICIENT_TX_FEE, the actual transaction fee that would be + * required to execute the transaction. + */ + uint64 cost = 2; } diff --git a/services/unchecked_submit.proto b/services/unchecked_submit.proto index 00c6e812..d3311614 100644 --- a/services/unchecked_submit.proto +++ b/services/unchecked_submit.proto @@ -25,9 +25,13 @@ package proto; option java_package = "com.hederahashgraph.api.proto.java"; option java_multiple_files = true; -/* -Submit an arbitrary (serialized) Transaction to the network without prechecks. Requires superuser privileges. -*/ +/** + * Submit an arbitrary (serialized) Transaction to the network without prechecks. Requires superuser + * privileges. + */ message UncheckedSubmitBody { - bytes transactionBytes = 1; // The serialized bytes of the Transaction to be submitted without prechecks + /** + * The serialized bytes of the Transaction to be submitted without prechecks + */ + bytes transactionBytes = 1; } diff --git a/streams/account_balance_file.proto b/streams/account_balance_file.proto index 832d1db0..4c589080 100644 --- a/streams/account_balance_file.proto +++ b/streams/account_balance_file.proto @@ -29,19 +29,51 @@ import "basic_types.proto"; import "timestamp.proto"; message TokenUnitBalance { - TokenID tokenId = 1; // A unique token id - uint64 balance = 2; // Number of transferable units of the identified token. For token of type FUNGIBLE_COMMON - balance in the smallest denomination. For token of type NON_FUNGIBLE_UNIQUE - the number of NFTs held by the account + /** + * A unique token id + */ + TokenID tokenId = 1; + + /** + * Number of transferable units of the identified token. For token of type FUNGIBLE_COMMON - + * balance in the smallest denomination. For token of type NON_FUNGIBLE_UNIQUE - the number of + * NFTs held by the account + */ + uint64 balance = 2; } -/* Includes all currency balances (both hbar and token) of a single account in the ledger. */ +/** + * Includes all currency balances (both hbar and token) of a single account in the ledger. + */ message SingleAccountBalances { - AccountID accountID = 1; // The account - uint64 hbarBalance = 2; // The account's hbar balance - repeated TokenUnitBalance tokenUnitBalances = 3; // The list of the account's token balances + /** + * The account + */ + AccountID accountID = 1; + + /** + * The account's hbar balance + */ + uint64 hbarBalance = 2; + + /** + * The list of the account's token balances + */ + repeated TokenUnitBalance tokenUnitBalances = 3; } -/* Includes all currency balances (both hbar and token) of all accounts in the ledger. */ +/** + * Includes all currency balances (both hbar and token) of all accounts in the ledger. + */ message AllAccountBalances { - Timestamp consensusTimestamp = 1; // An instant in consensus time - repeated SingleAccountBalances allAccounts = 2; // The list of account balances for all accounts, after handling all transactions with consensus timestamp up to and including the above instant + /** + * An instant in consensus time + */ + Timestamp consensusTimestamp = 1; + + /** + * The list of account balances for all accounts, after handling all transactions with consensus + * timestamp up to and including the above instant + */ + repeated SingleAccountBalances allAccounts = 2; }