diff --git a/scripts/update_protobufs.py b/scripts/update_protobufs.py index d6efa1ccd..0777e5ced 100755 --- a/scripts/update_protobufs.py +++ b/scripts/update_protobufs.py @@ -31,7 +31,7 @@ def go_to_script_dir(): PROTO_GIT_REMOTE = "https://github.com/hashgraph/hedera-services.git" -PROTO_GIT_PATH = os.path.join("hiero-protos-git") +PROTO_GIT_PATH = os.path.join("hedera-protos-git") PROTO_GIT_REF = sys.argv[1] if len(sys.argv)>1 else "" @@ -43,10 +43,10 @@ def go_to_script_dir(): FREEZE_TYPE_PATH = os.path.join(PROTO_IN_PATH, "freeze_type.proto") -MAIN_PATH = os.path.join("..", "sdk-java", "src", "main") +MAIN_PATH = os.path.join("..", "sdk", "src", "main") PROTO_OUT_PATH = os.path.join(MAIN_PATH, "proto") PROTO_MIRROR_OUT_PATH = os.path.join(PROTO_OUT_PATH, "mirror") -JAVA_OUT_PATH = os.path.join(MAIN_PATH, "java", "org", "hiero", "sdk", "java") +JAVA_OUT_PATH = os.path.join(MAIN_PATH, "java", "com", "hedera", "hashgraph", "sdk") REQUEST_TYPE_OUT_PATH = os.path.join(JAVA_OUT_PATH, "RequestType.java") STATUS_OUT_PATH = os.path.join(JAVA_OUT_PATH, "Status.java") FEE_DATA_TYPE_OUT_PATH = os.path.join(JAVA_OUT_PATH, "FeeDataType.java") @@ -100,7 +100,7 @@ def do_replacements_proto_imports(s, replacements): for r in replacements: # Check if the replacement should be skipped # Skip statements like `import "google/protobuf/wrappers.proto"` - # to update imports ONLY referred to hiero protobufs + # to update imports ONLY referred to hedera protobufs if 'google' in s: continue s = re.sub(r[0], r[1], s) @@ -136,7 +136,7 @@ def ensure_protobufs(): run_command("git", "clone", PROTO_GIT_REMOTE, PROTO_GIT_PATH) os.chdir(PROTO_GIT_PATH) run_command("git", "fetch") - checkout_ref = PROTO_GIT_REF if PROTO_GIT_REF else get_latest_tag() + checkout_ref = "v0.59.0-alpha.0" print(f">>> Checking out {checkout_ref}") run_command("git", "checkout", checkout_ref) if is_branch(checkout_ref): @@ -298,11 +298,6 @@ def output_java_file(out_path, section_list): out_file.write(section) out_file.close() - - - - - def add_to_RequestType(original_name, cap_snake_name, comment_lines): RequestType_sections[1] += \ generate_enum(original_name, cap_snake_name, comment_lines, "HederaFunctionality", 1) diff --git a/sdk/src/main/java/com/hedera/hashgraph/sdk/AccountStakersQuery.java b/sdk/src/main/java/com/hedera/hashgraph/sdk/AccountStakersQuery.java deleted file mode 100644 index 168b889b3..000000000 --- a/sdk/src/main/java/com/hedera/hashgraph/sdk/AccountStakersQuery.java +++ /dev/null @@ -1,96 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -package com.hedera.hashgraph.sdk; - -import com.hedera.hashgraph.sdk.proto.CryptoGetStakersQuery; -import com.hedera.hashgraph.sdk.proto.CryptoServiceGrpc; -import com.hedera.hashgraph.sdk.proto.QueryHeader; -import com.hedera.hashgraph.sdk.proto.Response; -import com.hedera.hashgraph.sdk.proto.ResponseHeader; -import io.grpc.MethodDescriptor; -import java.util.ArrayList; -import java.util.List; -import java.util.Objects; -import javax.annotation.Nullable; - -/** - * 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. - */ -public final class AccountStakersQuery extends Query, AccountStakersQuery> { - @Nullable - private AccountId accountId = null; - - /** - * Constructor. - */ - public AccountStakersQuery() {} - - /** - * Extract the account id. - * - * @return the account id - */ - @Nullable - public AccountId getAccountId() { - return accountId; - } - - /** - * Sets the Account ID for which the records should be retrieved. - * - * @param accountId The AccountId to be set - * @return {@code this} - */ - public AccountStakersQuery setAccountId(AccountId accountId) { - Objects.requireNonNull(accountId); - this.accountId = accountId; - return this; - } - - @Override - void validateChecksums(Client client) throws BadEntityIdException { - if (accountId != null) { - accountId.validateChecksum(client); - } - } - - @Override - void onMakeRequest(com.hedera.hashgraph.sdk.proto.Query.Builder queryBuilder, QueryHeader header) { - var builder = CryptoGetStakersQuery.newBuilder(); - - if (accountId != null) { - builder.setAccountID(accountId.toProtobuf()); - } - - queryBuilder.setCryptoGetProxyStakers(builder.setHeader(header)); - } - - @Override - ResponseHeader mapResponseHeader(Response response) { - return response.getCryptoGetProxyStakers().getHeader(); - } - - @Override - QueryHeader mapRequestHeader(com.hedera.hashgraph.sdk.proto.Query request) { - return request.getCryptoGetProxyStakers().getHeader(); - } - - @Override - List mapResponse(Response response, AccountId nodeId, com.hedera.hashgraph.sdk.proto.Query request) { - var rawStakers = response.getCryptoGetProxyStakers().getStakers(); - var stakers = new ArrayList(rawStakers.getProxyStakerCount()); - - for (var i = 0; i < rawStakers.getProxyStakerCount(); ++i) { - stakers.add(ProxyStaker.fromProtobuf(rawStakers.getProxyStaker(i))); - } - - return stakers; - } - - @Override - MethodDescriptor getMethodDescriptor() { - return CryptoServiceGrpc.getGetStakersByAccountIDMethod(); - } -} diff --git a/sdk/src/main/java/com/hedera/hashgraph/sdk/FeeDataType.java b/sdk/src/main/java/com/hedera/hashgraph/sdk/FeeDataType.java index 43b39cc5f..80fcafa74 100644 --- a/sdk/src/main/java/com/hedera/hashgraph/sdk/FeeDataType.java +++ b/sdk/src/main/java/com/hedera/hashgraph/sdk/FeeDataType.java @@ -8,36 +8,45 @@ */ public enum FeeDataType { /** - * The resource prices have no special scope + * The resource cost for the transaction type has no additional attributes */ DEFAULT(SubType.DEFAULT), /** - * The resource prices are scoped to an operation on a fungible common token + * The resource cost for the transaction type includes an operation on a + * fungible/common token */ TOKEN_FUNGIBLE_COMMON(SubType.TOKEN_FUNGIBLE_COMMON), /** - * The resource prices are scoped to an operation on a non-fungible unique token + * The resource cost for the transaction type includes an operation on + * a non-fungible/unique token */ TOKEN_NON_FUNGIBLE_UNIQUE(SubType.TOKEN_NON_FUNGIBLE_UNIQUE), /** - * The resource prices are scoped to an operation on a fungible common - * token with a custom fee schedule + * The resource cost for the transaction type includes an operation on a + * fungible/common token with a custom fee schedule */ TOKEN_FUNGIBLE_COMMON_WITH_CUSTOM_FEES(SubType.TOKEN_FUNGIBLE_COMMON_WITH_CUSTOM_FEES), /** - * The resource prices are scoped to an operation on a non-fungible unique - * token with a custom fee schedule + * The resource cost for the transaction type includes an operation on a + * non-fungible/unique token with a custom fee schedule */ TOKEN_NON_FUNGIBLE_UNIQUE_WITH_CUSTOM_FEES(SubType.TOKEN_NON_FUNGIBLE_UNIQUE_WITH_CUSTOM_FEES), /** - * The resource prices are scoped to a ScheduleCreate containing a ContractCall. + * The resource cost for the transaction type includes a ScheduleCreate + * containing a ContractCall. */ - SCHEDULE_CREATE_CONTRACT_CALL(SubType.SCHEDULE_CREATE_CONTRACT_CALL); + SCHEDULE_CREATE_CONTRACT_CALL(SubType.SCHEDULE_CREATE_CONTRACT_CALL), + + /** + * The resource cost for the transaction type includes a TopicCreate + * with custom fees. + */ + TOPIC_CREATE_WITH_CUSTOM_FEES(SubType.TOPIC_CREATE_WITH_CUSTOM_FEES); final SubType code; @@ -53,6 +62,7 @@ static FeeDataType valueOf(SubType code) { case TOKEN_FUNGIBLE_COMMON_WITH_CUSTOM_FEES -> TOKEN_FUNGIBLE_COMMON_WITH_CUSTOM_FEES; case TOKEN_NON_FUNGIBLE_UNIQUE_WITH_CUSTOM_FEES -> TOKEN_NON_FUNGIBLE_UNIQUE_WITH_CUSTOM_FEES; case SCHEDULE_CREATE_CONTRACT_CALL -> SCHEDULE_CREATE_CONTRACT_CALL; + case TOPIC_CREATE_WITH_CUSTOM_FEES -> TOPIC_CREATE_WITH_CUSTOM_FEES; default -> throw new IllegalStateException("(BUG) unhandled SubType (FeeDataType)"); }; } @@ -66,6 +76,7 @@ public String toString() { case TOKEN_FUNGIBLE_COMMON_WITH_CUSTOM_FEES -> "TOKEN_FUNGIBLE_COMMON_WITH_CUSTOM_FEES"; case TOKEN_NON_FUNGIBLE_UNIQUE_WITH_CUSTOM_FEES -> "TOKEN_NON_FUNGIBLE_UNIQUE_WITH_CUSTOM_FEES"; case SCHEDULE_CREATE_CONTRACT_CALL -> "SCHEDULE_CREATE_CONTRACT_CALL"; + case TOPIC_CREATE_WITH_CUSTOM_FEES -> "TOPIC_CREATE_WITH_CUSTOM_FEES"; }; } } diff --git a/sdk/src/main/java/com/hedera/hashgraph/sdk/FreezeType.java b/sdk/src/main/java/com/hedera/hashgraph/sdk/FreezeType.java index 08baf11f4..a8e162184 100644 --- a/sdk/src/main/java/com/hedera/hashgraph/sdk/FreezeType.java +++ b/sdk/src/main/java/com/hedera/hashgraph/sdk/FreezeType.java @@ -6,40 +6,95 @@ */ public enum FreezeType { /** - * An (invalid) default value for this enum, to ensure the client explicitly sets - * the intended type of freeze transaction. + * An invalid freeze type. + *

+ * The first value in a protobuf enum is a default value. This default + * is RECOMMENDED to be an invalid value to aid in detecting unset fields. */ UNKNOWN_FREEZE_TYPE(com.hedera.hashgraph.sdk.proto.FreezeType.UNKNOWN_FREEZE_TYPE), /** - * Freezes the network at the specified time. The start_time field must be provided and - * must reference a future time. Any values specified for the update_file and file_hash - * fields will be ignored. This transaction does not perform any network changes or - * upgrades and requires manual intervention to restart the network. + * Freeze the network, and take no further action. + *

+ * The `start_time` field is REQUIRED, MUST be strictly later than the + * consensus time when this transaction is handled, and SHOULD be between + * `300` and `3600` seconds after the transaction identifier + * `transactionValidStart` field.
+ * The fields `update_file` and `file_hash` SHALL be ignored.
+ * A `FREEZE_ONLY` transaction SHALL NOT perform any network + * changes or upgrades.
+ * After this freeze is processed manual intervention is REQUIRED + * to restart the network. */ FREEZE_ONLY(com.hedera.hashgraph.sdk.proto.FreezeType.FREEZE_ONLY), /** - * A non-freezing operation that initiates network wide preparation in advance of a - * scheduled freeze upgrade. The update_file and file_hash fields must be provided and - * valid. The start_time field may be omitted and any value present will be ignored. + * This freeze type does not freeze the network, but begins + * "preparation" to upgrade the network. + *

+ * The fields `update_file` and `file_hash` are REQUIRED + * and MUST be valid.
+ * The `start_time` field SHALL be ignored.
+ * A `PREPARE_UPGRADE` transaction SHALL NOT freeze the network or + * interfere with general transaction processing.
+ * If this freeze type is initiated after a `TELEMETRY_UPGRADE`, the + * prepared telemetry upgrade SHALL be reset and all telemetry upgrade + * artifacts in the filesystem SHALL be deleted.
+ * At some point after this freeze type completes (dependent on the size + * of the upgrade file), the network SHALL be prepared to complete + * a software upgrade of all nodes. */ PREPARE_UPGRADE(com.hedera.hashgraph.sdk.proto.FreezeType.PREPARE_UPGRADE), /** - * Freezes the network at the specified time and performs the previously prepared - * automatic upgrade across the entire network. + * Freeze the network to perform a software upgrade. + *

+ * The `start_time` field is REQUIRED, MUST be strictly later than the + * consensus time when this transaction is handled, and SHOULD be between + * `300` and `3600` seconds after the transaction identifier + * `transactionValidStart` field.
+ * A software upgrade file MUST be prepared prior to this transaction.
+ * After this transaction completes, the network SHALL initiate an + * upgrade and restart of all nodes at the start time specified. */ FREEZE_UPGRADE(com.hedera.hashgraph.sdk.proto.FreezeType.FREEZE_UPGRADE), /** - * Aborts a pending network freeze operation. + * Abort a pending network freeze operation. + *

+ * All fields SHALL be ignored for this freeze type.
+ * This freeze type MAY be submitted after a `FREEZE_ONLY`, + * `FREEZE_UPGRADE`, or `TELEMETRY_UPGRADE` is initiated.
+ * This freeze type MUST be submitted and reach consensus + * before the `start_time` designated for the current pending + * freeze to be effective.
+ * After this freeze type is processed, the upgrade file hash + * and pending freeze start time stored in the network SHALL + * be reset to default (empty) values. */ FREEZE_ABORT(com.hedera.hashgraph.sdk.proto.FreezeType.FREEZE_ABORT), /** - * Performs an immediate upgrade on auxilary services and containers providing - * telemetry/metrics. Does not impact network operations. + * Prepare an upgrade of auxiliary services and containers + * providing telemetry/metrics. + *

+ * The `start_time` field is REQUIRED, MUST be strictly later than the + * consensus time when this transaction is handled, and SHOULD be between + * `300` and `3600` seconds after the transaction identifier + * `transactionValidStart` field.
+ * The `update_file` field is REQUIRED and MUST be valid.
+ * A `TELEMETRY_UPGRADE` transaction SHALL NOT freeze the network or + * interfere with general transaction processing.
+ * This freeze type MUST NOT be initiated between a `PREPARE_UPGRADE` + * and `FREEZE_UPGRADE`. If this freeze type is initiated after a + * `PREPARE_UPGRADE`, the prepared upgrade SHALL be reset and all software + * upgrade artifacts in the filesystem SHALL be deleted.
+ * At some point after this freeze type completes (dependent on the + * size of the upgrade file), the network SHALL automatically upgrade + * the telemetry/metrics services and containers as directed in + * the specified telemetry upgrade file. + *

The condition that `start_time` is REQUIRED is an + * historical anomaly and SHOULD change in a future release.
*/ TELEMETRY_UPGRADE(com.hedera.hashgraph.sdk.proto.FreezeType.TELEMETRY_UPGRADE); diff --git a/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashAddTransaction.java b/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashAddTransaction.java index 6f9fb4241..88036645a 100644 --- a/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashAddTransaction.java +++ b/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashAddTransaction.java @@ -19,9 +19,13 @@ import javax.annotation.Nullable; /** + * @deprecated + * This transaction is obsolete, not supported, and SHALL fail with a + * pre-check result of `NOT_SUPPORTED`. * 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. */ +@Deprecated public final class LiveHashAddTransaction extends Transaction { @Nullable private AccountId accountId = null; diff --git a/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashDeleteTransaction.java b/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashDeleteTransaction.java index a4ee7dfa3..97e76237d 100644 --- a/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashDeleteTransaction.java +++ b/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashDeleteTransaction.java @@ -15,9 +15,13 @@ import javax.annotation.Nullable; /** + * @deprecated + * This transaction is obsolete, not supported, and SHALL fail with a + * pre-check result of `NOT_SUPPORTED`. * 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. */ +@Deprecated public final class LiveHashDeleteTransaction extends Transaction { @Nullable private AccountId accountId = null; diff --git a/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashQuery.java b/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashQuery.java index af2e88e1e..2060e5157 100644 --- a/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashQuery.java +++ b/sdk/src/main/java/com/hedera/hashgraph/sdk/LiveHashQuery.java @@ -13,8 +13,10 @@ import javax.annotation.Nullable; /** + * @deprecated This query is no longer supported. * Requests a livehash associated to an account. */ +@Deprecated public final class LiveHashQuery extends Query { @Nullable private AccountId accountId = null; diff --git a/sdk/src/main/java/com/hedera/hashgraph/sdk/RequestType.java b/sdk/src/main/java/com/hedera/hashgraph/sdk/RequestType.java index c7e9acff6..42a19c666 100644 --- a/sdk/src/main/java/com/hedera/hashgraph/sdk/RequestType.java +++ b/sdk/src/main/java/com/hedera/hashgraph/sdk/RequestType.java @@ -8,371 +8,414 @@ */ public enum RequestType { /** - * UNSPECIFIED - Need to keep first value as unspecified because first element is ignored and - * not parsed (0 is ignored by parser) + * FUTURE - Uncomment when https://github.com/hashgraph/pbj/issues/339 is fixed; + * currently the PBJ-generated unit tests fail when using reserved ordinals + * reserved 96, 97, 98, 99; + * Unused - The first value is unused because this default value is + * ambiguous with an "unset" value and therefore should not be used. */ NONE(HederaFunctionality.NONE), /** - * crypto transfer + * Transfer tokens among accounts. */ CRYPTO_TRANSFER(HederaFunctionality.CryptoTransfer), /** - * crypto update account + * Update an account. */ CRYPTO_UPDATE(HederaFunctionality.CryptoUpdate), /** - * crypto delete account + * Delete an account. */ CRYPTO_DELETE(HederaFunctionality.CryptoDelete), /** - * Add a livehash to a crypto account + * Add a livehash to an account */ CRYPTO_ADD_LIVE_HASH(HederaFunctionality.CryptoAddLiveHash), /** - * Delete a livehash from a crypto account + * Delete a livehash from an account */ CRYPTO_DELETE_LIVE_HASH(HederaFunctionality.CryptoDeleteLiveHash), /** - * Smart Contract Call + * Execute a smart contract call. */ CONTRACT_CALL(HederaFunctionality.ContractCall), /** - * Smart Contract Create Contract + * Create a smart contract. */ CONTRACT_CREATE(HederaFunctionality.ContractCreate), /** - * Smart Contract update contract + * Update a smart contract. */ CONTRACT_UPDATE(HederaFunctionality.ContractUpdate), /** - * File Operation create file + * Create a "file" stored in the ledger. */ FILE_CREATE(HederaFunctionality.FileCreate), /** - * File Operation append file + * Append data to a "file" stored in the ledger. */ FILE_APPEND(HederaFunctionality.FileAppend), /** - * File Operation update file + * Update a "file" stored in the ledger. */ FILE_UPDATE(HederaFunctionality.FileUpdate), /** - * File Operation delete file + * Delete a "file" stored in the ledger. */ FILE_DELETE(HederaFunctionality.FileDelete), /** - * crypto get account balance + * Get the balance for an account. */ CRYPTO_GET_ACCOUNT_BALANCE(HederaFunctionality.CryptoGetAccountBalance), /** - * crypto get account record + * Get a full account record. */ CRYPTO_GET_ACCOUNT_RECORDS(HederaFunctionality.CryptoGetAccountRecords), /** - * Crypto get info + * Get information about a token. */ CRYPTO_GET_INFO(HederaFunctionality.CryptoGetInfo), /** - * Smart Contract Call + * Execute a local smart contract call.
+ * Used by contracts to call other contracts. */ CONTRACT_CALL_LOCAL(HederaFunctionality.ContractCallLocal), /** - * Smart Contract get info + * Get information about a smart contract. */ CONTRACT_GET_INFO(HederaFunctionality.ContractGetInfo), /** - * Smart Contract, get the runtime code + * Get the compiled bytecode that implements a smart contract. */ CONTRACT_GET_BYTECODE(HederaFunctionality.ContractGetBytecode), /** - * Smart Contract, get by solidity ID + * Get a smart contract record by reference to the solidity ID. */ GET_BY_SOLIDITY_ID(HederaFunctionality.GetBySolidityID), /** - * Smart Contract, get by key + * Get a smart contract by reference to the contract key. */ GET_BY_KEY(HederaFunctionality.GetByKey), /** - * Get a live hash from a crypto account + * Get the live hash for an account */ CRYPTO_GET_LIVE_HASH(HederaFunctionality.CryptoGetLiveHash), /** - * Crypto, get the stakers for the node + * Get the accounts proxy staking to a given account. */ CRYPTO_GET_STAKERS(HederaFunctionality.CryptoGetStakers), /** - * File Operations get file contents + * Get the contents of a "file" stored in the ledger. */ FILE_GET_CONTENTS(HederaFunctionality.FileGetContents), /** - * File Operations get the info of the file + * Get the metadata for a "file" stored in the ledger. */ FILE_GET_INFO(HederaFunctionality.FileGetInfo), /** - * Crypto get the transaction records + * Get transaction record(s) for a specified transaction ID. */ TRANSACTION_GET_RECORD(HederaFunctionality.TransactionGetRecord), /** - * Contract get the transaction records + * Get all transaction records for a specified contract ID in + * the past 24 hours.
+ * deprecated since version 0.9.0 */ CONTRACT_GET_RECORDS(HederaFunctionality.ContractGetRecords), /** - * crypto create account + * Create a new account */ CRYPTO_CREATE(HederaFunctionality.CryptoCreate), /** - * system delete file + * Delete a "system" "file" stored in the ledger.
+ * "System" files are files with special purpose and ID values within a + * specific range.
+ * These files require additional controls and can only be deleted when + * authorized by accounts with elevated privilege. */ SYSTEM_DELETE(HederaFunctionality.SystemDelete), /** - * system undelete file + * Undo the delete of a "system" "file" stored in the ledger.
+ * "System" files are files with special purpose and ID values within a + * specific range.
+ * These files require additional controls and can only be deleted when + * authorized by accounts with elevated privilege. This operation allows + * such files to be restored, within a reasonable timeframe, if + * deleted improperly. */ SYSTEM_UNDELETE(HederaFunctionality.SystemUndelete), /** - * delete contract + * Delete a smart contract */ CONTRACT_DELETE(HederaFunctionality.ContractDelete), /** - * freeze + * Stop all processing and "freeze" the entire network.
+ * This is generally sent immediately prior to upgrading the network.
+ * After processing this transactions all nodes enter a quiescent state. */ FREEZE(HederaFunctionality.Freeze), /** - * Create Tx Record + * Create a Transaction Record.
+ * This appears to be purely internal and unused. */ CREATE_TRANSACTION_RECORD(HederaFunctionality.CreateTransactionRecord), /** - * Crypto Auto Renew + * Auto-renew an account.
+ * This is used for internal fee calculations. */ CRYPTO_ACCOUNT_AUTO_RENEW(HederaFunctionality.CryptoAccountAutoRenew), /** - * Contract Auto Renew + * Auto-renew a smart contract.
+ * This is used for internal fee calculations. */ CONTRACT_AUTO_RENEW(HederaFunctionality.ContractAutoRenew), /** - * Get Version + * Get version information for the ledger.
+ * This returns a the version of the software currently running the network + * for both the protocol buffers and the network services (node). */ GET_VERSION_INFO(HederaFunctionality.GetVersionInfo), /** - * Transaction Get Receipt + * Get a receipt for a specified transaction ID. */ TRANSACTION_GET_RECEIPT(HederaFunctionality.TransactionGetReceipt), /** - * Create Topic + * Create a topic for the Hedera Consensus Service (HCS). */ CONSENSUS_CREATE_TOPIC(HederaFunctionality.ConsensusCreateTopic), /** - * Update Topic + * Update an HCS topic. */ CONSENSUS_UPDATE_TOPIC(HederaFunctionality.ConsensusUpdateTopic), /** - * Delete Topic + * Delete an HCS topic. */ CONSENSUS_DELETE_TOPIC(HederaFunctionality.ConsensusDeleteTopic), /** - * Get Topic information + * Get metadata (information) for an HCS topic. */ CONSENSUS_GET_TOPIC_INFO(HederaFunctionality.ConsensusGetTopicInfo), /** - * Submit message to topic + * Publish a message to an HCS topic. */ CONSENSUS_SUBMIT_MESSAGE(HederaFunctionality.ConsensusSubmitMessage), + /** + * Submit a transaction, bypassing intake checking. + * Only enabled in local-mode. + */ UNCHECKED_SUBMIT(HederaFunctionality.UncheckedSubmit), /** - * Create Token + * Create a token for the Hedera Token Service (HTS). */ TOKEN_CREATE(HederaFunctionality.TokenCreate), /** - * Get Token information + * Get metadata (information) for an HTS token. */ TOKEN_GET_INFO(HederaFunctionality.TokenGetInfo), /** - * Freeze Account + * Freeze a specific account with respect to a specific HTS token. + *

+ * Once this transaction completes that account CANNOT send or receive + * the specified token. */ TOKEN_FREEZE_ACCOUNT(HederaFunctionality.TokenFreezeAccount), /** - * Unfreeze Account + * Remove a "freeze" from an account with respect to a specific HTS token. */ TOKEN_UNFREEZE_ACCOUNT(HederaFunctionality.TokenUnfreezeAccount), /** - * Grant KYC to Account + * Grant KYC status to an account for a specific HTS token. */ TOKEN_GRANT_KYC_TO_ACCOUNT(HederaFunctionality.TokenGrantKycToAccount), /** - * Revoke KYC from Account + * Revoke KYC status from an account for a specific HTS token. */ TOKEN_REVOKE_KYC_FROM_ACCOUNT(HederaFunctionality.TokenRevokeKycFromAccount), /** - * Delete Token + * Delete a specific HTS token. */ TOKEN_DELETE(HederaFunctionality.TokenDelete), /** - * Update Token + * Update a specific HTS token. */ TOKEN_UPDATE(HederaFunctionality.TokenUpdate), /** - * Mint tokens to treasury + * Mint HTS token amounts to the treasury account for that token. */ TOKEN_MINT(HederaFunctionality.TokenMint), /** - * Burn tokens from treasury + * Burn HTS token amounts from the treasury account for that token. */ TOKEN_BURN(HederaFunctionality.TokenBurn), /** - * Wipe token amount from Account holder + * Wipe all amounts for a specific HTS token from a specified account. */ TOKEN_ACCOUNT_WIPE(HederaFunctionality.TokenAccountWipe), /** - * Associate tokens to an account + * Associate a specific HTS token to an account. */ TOKEN_ASSOCIATE_TO_ACCOUNT(HederaFunctionality.TokenAssociateToAccount), /** - * Dissociate tokens from an account + * Dissociate a specific HTS token from an account. */ TOKEN_DISSOCIATE_FROM_ACCOUNT(HederaFunctionality.TokenDissociateFromAccount), /** - * Create Scheduled Transaction + * Create a scheduled transaction */ SCHEDULE_CREATE(HederaFunctionality.ScheduleCreate), /** - * Delete Scheduled Transaction + * Delete a scheduled transaction */ SCHEDULE_DELETE(HederaFunctionality.ScheduleDelete), /** - * Sign Scheduled Transaction + * Sign a scheduled transaction */ SCHEDULE_SIGN(HederaFunctionality.ScheduleSign), /** - * Get Scheduled Transaction Information + * Get metadata (information) for a scheduled transaction */ SCHEDULE_GET_INFO(HederaFunctionality.ScheduleGetInfo), /** - * Get Token Account Nft Information + * Get NFT metadata (information) for a range of NFTs associated to a + * specific non-fungible/unique HTS token and owned by a specific account. */ TOKEN_GET_ACCOUNT_NFT_INFOS(HederaFunctionality.TokenGetAccountNftInfos), /** - * Get Token Nft Information + * Get metadata (information) for a specific NFT identified by token and + * serial number. */ TOKEN_GET_NFT_INFO(HederaFunctionality.TokenGetNftInfo), /** - * Get Token Nft List Information + * Get NFT metadata (information) for a range of NFTs associated to a + * specific non-fungible/unique HTS token. */ TOKEN_GET_NFT_INFOS(HederaFunctionality.TokenGetNftInfos), /** - * Update a token's custom fee schedule, if permissible + * Update a token's custom fee schedule. + *

+ * If a transaction of this type is not signed by the token + * `fee_schedule_key` it SHALL fail with INVALID_SIGNATURE, or + * TOKEN_HAS_NO_FEE_SCHEDULE_KEY if there is no `fee_schedule_key` set. */ TOKEN_FEE_SCHEDULE_UPDATE(HederaFunctionality.TokenFeeScheduleUpdate), /** - * Get execution time(s) by TransactionID, if available + * Get execution time(s) for one or more "recent" TransactionIDs. */ NETWORK_GET_EXECUTION_TIME(HederaFunctionality.NetworkGetExecutionTime), /** - * Pause the Token + * Pause a specific HTS token */ TOKEN_PAUSE(HederaFunctionality.TokenPause), /** - * Unpause the Token + * Unpause a paused HTS token. */ TOKEN_UNPAUSE(HederaFunctionality.TokenUnpause), /** - * Approve allowance for a spender relative to the owner account + * Approve an allowance for a spender relative to the owner account, which + * MUST sign the transaction. */ CRYPTO_APPROVE_ALLOWANCE(HederaFunctionality.CryptoApproveAllowance), /** - * Deletes granted allowances on owner account + * Delete (unapprove) an allowance previously approved + * for the owner account. */ CRYPTO_DELETE_ALLOWANCE(HederaFunctionality.CryptoDeleteAllowance), /** - * Gets all the information about an account, including balance and allowances. This does not get the list of - * account records. + * Get all the information about an account, including balance + * and allowances.
+ * This does not get a list of account records. */ GET_ACCOUNT_DETAILS(HederaFunctionality.GetAccountDetails), /** - * Ethereum Transaction + * Perform an Ethereum (EVM) transaction.
+ * CallData may be inline if small, or in a "file" if large. */ ETHEREUM_TRANSACTION(HederaFunctionality.EthereumTransaction), /** - * Updates the staking info at the end of staking period to indicate new staking period has started. + * Used to indicate when the network has updated the staking information + * at the end of a staking period and to indicate a new staking period + * has started. */ NODE_STAKE_UPDATE(HederaFunctionality.NodeStakeUpdate), /** - * Generates a pseudorandom number. + * Generate and return a pseudorandom number based on network state. */ PRNG(HederaFunctionality.UtilPrng), /** - * Get a record for a transaction. + * Get a record for a "recent" transaction. */ TRANSACTION_GET_FAST_RECORD(HederaFunctionality.TransactionGetFastRecord), @@ -397,7 +440,8 @@ public enum RequestType { NODE_DELETE(HederaFunctionality.NodeDelete), /** - * Transfer one or more token balances held by the requesting account to the treasury for each token type. + * Transfer one or more token balances held by the requesting account + * to the treasury for each token type. */ TOKEN_REJECT(HederaFunctionality.TokenReject), @@ -407,7 +451,8 @@ public enum RequestType { TOKEN_AIRDROP(HederaFunctionality.TokenAirdrop), /** - * Remove one or more pending airdrops from state on behalf of the sender(s) for each airdrop. + * Remove one or more pending airdrops from state on behalf of + * the sender(s) for each airdrop. */ TOKEN_CANCEL_AIRDROP(HederaFunctionality.TokenCancelAirdrop), @@ -417,19 +462,24 @@ public enum RequestType { TOKEN_CLAIM_AIRDROP(HederaFunctionality.TokenClaimAirdrop), /** - * A message produced as part of Threshold Signature Scheme (TSS) processing. + * Submit a signature of a state root hash gossiped to other nodes + */ + STATE_SIGNATURE_TRANSACTION(HederaFunctionality.StateSignatureTransaction), + + /** + * Sign a particular history assembly. */ - TSS_MESSAGE(HederaFunctionality.TssMessage), + HISTORY_ASSEMBLY_SIGNATURE(HederaFunctionality.HistoryAssemblySignature), /** - * Submit a vote as part of the Threshold Signature Scheme (TSS) processing. + * Publish a roster history proof key to the network. */ - TSS_VOTE(HederaFunctionality.TssVote), + HISTORY_PROOF_KEY_PUBLICATION(HederaFunctionality.HistoryProofKeyPublication), /** - * Submit a node signature as part of the Threshold Signature Scheme (TSS) processing. + * Vote for a particular history proof. */ - TSS_SHARE_SIGNATURE(HederaFunctionality.TssShareSignature); + HISTORY_PROOF_VOTE(HederaFunctionality.HistoryProofVote); final HederaFunctionality code; @@ -521,9 +571,10 @@ static RequestType valueOf(HederaFunctionality code) { case TokenAirdrop -> TOKEN_AIRDROP; case TokenCancelAirdrop -> TOKEN_CANCEL_AIRDROP; case TokenClaimAirdrop -> TOKEN_CLAIM_AIRDROP; - case TssMessage -> TSS_MESSAGE; - case TssVote -> TSS_VOTE; - case TssShareSignature -> TSS_SHARE_SIGNATURE; + case StateSignatureTransaction -> STATE_SIGNATURE_TRANSACTION; + case HistoryAssemblySignature -> HISTORY_ASSEMBLY_SIGNATURE; + case HistoryProofKeyPublication -> HISTORY_PROOF_KEY_PUBLICATION; + case HistoryProofVote -> HISTORY_PROOF_VOTE; default -> throw new IllegalStateException("(BUG) unhandled HederaFunctionality"); }; } @@ -613,9 +664,10 @@ public String toString() { case TOKEN_AIRDROP -> "TOKEN_AIRDROP"; case TOKEN_CANCEL_AIRDROP -> "TOKEN_CANCEL_AIRDROP"; case TOKEN_CLAIM_AIRDROP -> "TOKEN_CLAIM_AIRDROP"; - case TSS_MESSAGE -> "TSS_MESSAGE"; - case TSS_VOTE -> "TSS_VOTE"; - case TSS_SHARE_SIGNATURE -> "TSS_SHARE_SIGNATURE"; + case STATE_SIGNATURE_TRANSACTION -> "STATE_SIGNATURE_TRANSACTION"; + case HISTORY_ASSEMBLY_SIGNATURE -> "HISTORY_ASSEMBLY_SIGNATURE"; + case HISTORY_PROOF_KEY_PUBLICATION -> "HISTORY_PROOF_KEY_PUBLICATION"; + case HISTORY_PROOF_VOTE -> "HISTORY_PROOF_VOTE"; }; } } diff --git a/sdk/src/main/java/com/hedera/hashgraph/sdk/Status.java b/sdk/src/main/java/com/hedera/hashgraph/sdk/Status.java index 361798b16..8870aaf03 100644 --- a/sdk/src/main/java/com/hedera/hashgraph/sdk/Status.java +++ b/sdk/src/main/java/com/hedera/hashgraph/sdk/Status.java @@ -456,12 +456,12 @@ public enum Status { INVALID_INITIAL_BALANCE(ResponseCodeEnum.INVALID_INITIAL_BALANCE), /** - * [Deprecated]. attempt to set negative receive record threshold + * Attempt to set negative receive record threshold */ INVALID_RECEIVE_RECORD_THRESHOLD(ResponseCodeEnum.INVALID_RECEIVE_RECORD_THRESHOLD), /** - * [Deprecated]. attempt to set negative send record threshold + * Attempt to set negative send record threshold */ INVALID_SEND_RECORD_THRESHOLD(ResponseCodeEnum.INVALID_SEND_RECORD_THRESHOLD), @@ -1258,7 +1258,7 @@ public enum Status { UNEXPECTED_TOKEN_DECIMALS(ResponseCodeEnum.UNEXPECTED_TOKEN_DECIMALS), /** - * [Deprecated] The proxy account id is invalid or does not exist. + * The proxy account id is invalid or does not exist. */ INVALID_PROXY_ACCOUNT_ID(ResponseCodeEnum.INVALID_PROXY_ACCOUNT_ID), @@ -1295,7 +1295,7 @@ public enum Status { NEGATIVE_ALLOWANCE_AMOUNT(ResponseCodeEnum.NEGATIVE_ALLOWANCE_AMOUNT), /** - * [Deprecated] The approveForAll flag cannot be set for a fungible token. + * The approveForAll flag cannot be set for a fungible token. */ CANNOT_APPROVE_FOR_ALL_FUNGIBLE_COMMON(ResponseCodeEnum.CANNOT_APPROVE_FOR_ALL_FUNGIBLE_COMMON), @@ -1321,13 +1321,13 @@ public enum Status { EMPTY_ALLOWANCES(ResponseCodeEnum.EMPTY_ALLOWANCES), /** - * [Deprecated] Spender is repeated more than once in Crypto or Token or NFT allowance lists in a single + * Spender is repeated more than once in Crypto or Token or NFT allowance lists in a single * CryptoApproveAllowance transaction. */ SPENDER_ACCOUNT_REPEATED_IN_ALLOWANCES(ResponseCodeEnum.SPENDER_ACCOUNT_REPEATED_IN_ALLOWANCES), /** - * [Deprecated] Serial numbers are repeated in nft allowance for a single spender account + * Serial numbers are repeated in nft allowance for a single spender account */ REPEATED_SERIAL_NUMS_IN_NFT_ALLOWANCES(ResponseCodeEnum.REPEATED_SERIAL_NUMS_IN_NFT_ALLOWANCES), @@ -1583,7 +1583,9 @@ public enum Status { /** * A transaction failed because the TLS certificate provided for the - * node is missing or invalid.
+ * node is missing or invalid. + *

+ * #### Probable Causes * The certificate MUST be a TLS certificate of a type permitted for gossip * signatures.
* The value presented MUST be a UTF-8 NFKD encoding of the TLS @@ -1595,7 +1597,9 @@ public enum Status { /** * A transaction failed because the hash provided for the gRPC certificate - * is present but invalid.
+ * is present but invalid. + *

+ * #### Probable Causes * The `grpc_certificate_hash` MUST be a SHA-384 hash.
* The input hashed MUST be a UTF-8 NFKD encoding of the actual TLS * certificate.
@@ -1681,17 +1685,18 @@ public enum Status { TOKEN_HAS_NO_METADATA_OR_SUPPLY_KEY(ResponseCodeEnum.TOKEN_HAS_NO_METADATA_OR_SUPPLY_KEY), /** - * The transaction attempted to the use an empty List of `PendingAirdropId`. + * The list of `PendingAirdropId`s is empty and MUST NOT be empty. */ EMPTY_PENDING_AIRDROP_ID_LIST(ResponseCodeEnum.EMPTY_PENDING_AIRDROP_ID_LIST), /** - * The transaction attempted to the same `PendingAirdropId` twice. + * A `PendingAirdropId` is repeated in a `claim` or `cancel` transaction. */ PENDING_AIRDROP_ID_REPEATED(ResponseCodeEnum.PENDING_AIRDROP_ID_REPEATED), /** - * The transaction attempted to use more than the allowed number of `PendingAirdropId`. + * The number of `PendingAirdropId` values in the list exceeds the maximum + * allowable number. */ PENDING_AIRDROP_ID_LIST_TOO_LONG(ResponseCodeEnum.PENDING_AIRDROP_ID_LIST_TOO_LONG), @@ -1702,8 +1707,9 @@ public enum Status { /** * The identified account is sender for one or more pending airdrop(s) - * and cannot be deleted.
- * Requester should cancel all pending airdrops before resending + * and cannot be deleted. + *

+ * The requester SHOULD cancel all pending airdrops before resending * this transaction. */ ACCOUNT_HAS_PENDING_AIRDROPS(ResponseCodeEnum.ACCOUNT_HAS_PENDING_AIRDROPS), @@ -1734,8 +1740,8 @@ public enum Status { * The token might be deleted, or the sender may not have enough tokens * to fulfill the offer. *

- * The client SHOULD query mirror node to determine the status of the pending - * airdrop and whether the sender can fulfill the offer. + * The client SHOULD query mirror node to determine the status of the + * pending airdrop and whether the sender can fulfill the offer. */ INVALID_TOKEN_IN_PENDING_AIRDROP(ResponseCodeEnum.INVALID_TOKEN_IN_PENDING_AIRDROP), @@ -1755,7 +1761,90 @@ public enum Status { * A scheduled transaction configured to wait for expiry to execute was not * given an explicit expiration time. */ - MISSING_EXPIRY_TIME(ResponseCodeEnum.MISSING_EXPIRY_TIME); + MISSING_EXPIRY_TIME(ResponseCodeEnum.MISSING_EXPIRY_TIME), + + /** + * A contract operation attempted to schedule another transaction after it + * had already scheduled a recursive contract call. + */ + NO_SCHEDULING_ALLOWED_AFTER_SCHEDULED_RECURSION(ResponseCodeEnum.NO_SCHEDULING_ALLOWED_AFTER_SCHEDULED_RECURSION), + + /** + * A contract can schedule recursive calls a finite number of times (this is + * approximately four million times with typical network configuration.) + */ + RECURSIVE_SCHEDULING_LIMIT_REACHED(ResponseCodeEnum.RECURSIVE_SCHEDULING_LIMIT_REACHED), + + /** + * The target network is waiting for the ledger ID to be set, which is a + * side effect of finishing the network's TSS construction. + */ + WAITING_FOR_LEDGER_ID(ResponseCodeEnum.WAITING_FOR_LEDGER_ID), + + /** + * The provided fee exempt key list size exceeded the limit. + */ + MAX_ENTRIES_FOR_FEE_EXEMPT_KEY_LIST_EXCEEDED(ResponseCodeEnum.MAX_ENTRIES_FOR_FEE_EXEMPT_KEY_LIST_EXCEEDED), + + /** + * The provided fee exempt key list contains duplicated keys. + */ + FEE_EXEMPT_KEY_LIST_CONTAINS_DUPLICATED_KEYS(ResponseCodeEnum.FEE_EXEMPT_KEY_LIST_CONTAINS_DUPLICATED_KEYS), + + /** + * The provided fee exempt key list contains an invalid key. + */ + INVALID_KEY_IN_FEE_EXEMPT_KEY_LIST(ResponseCodeEnum.INVALID_KEY_IN_FEE_EXEMPT_KEY_LIST), + + /** + * The provided fee schedule key contains an invalid key. + */ + INVALID_FEE_SCHEDULE_KEY(ResponseCodeEnum.INVALID_FEE_SCHEDULE_KEY), + + /** + * If a fee schedule key is not set when we create a topic + * we cannot add it on update. + */ + FEE_SCHEDULE_KEY_CANNOT_BE_UPDATED(ResponseCodeEnum.FEE_SCHEDULE_KEY_CANNOT_BE_UPDATED), + + /** + * If the topic's custom fees are updated the topic SHOULD have a + * fee schedule key + */ + FEE_SCHEDULE_KEY_NOT_SET(ResponseCodeEnum.FEE_SCHEDULE_KEY_NOT_SET), + + /** + * The fee amount is exceeding the amount that the payer + * is willing to pay. + */ + MAX_CUSTOM_FEE_LIMIT_EXCEEDED(ResponseCodeEnum.MAX_CUSTOM_FEE_LIMIT_EXCEEDED), + + /** + * There are no corresponding custom fees. + */ + NO_VALID_MAX_CUSTOM_FEE(ResponseCodeEnum.NO_VALID_MAX_CUSTOM_FEE), + + /** + * The provided list contains invalid max custom fee. + */ + INVALID_MAX_CUSTOM_FEES(ResponseCodeEnum.INVALID_MAX_CUSTOM_FEES), + + /** + * The provided max custom fee list contains fees with + * duplicate denominations. + */ + DUPLICATE_DENOMINATION_IN_MAX_CUSTOM_FEE_LIST(ResponseCodeEnum.DUPLICATE_DENOMINATION_IN_MAX_CUSTOM_FEE_LIST), + + /** + * The provided max custom fee list contains fees with + * duplicate account id. + */ + DUPLICATE_ACCOUNT_ID_IN_MAX_CUSTOM_FEE_LIST(ResponseCodeEnum.DUPLICATE_ACCOUNT_ID_IN_MAX_CUSTOM_FEE_LIST), + + /** + * Max custom fees list is not supported for this operation. + */ + MAX_CUSTOM_FEES_IS_NOT_SUPPORTED(ResponseCodeEnum.MAX_CUSTOM_FEES_IS_NOT_SUPPORTED); final ResponseCodeEnum code; @@ -2096,6 +2185,21 @@ static Status valueOf(ResponseCodeEnum code) { case SCHEDULE_EXPIRY_IS_BUSY -> SCHEDULE_EXPIRY_IS_BUSY; case INVALID_GRPC_CERTIFICATE_HASH -> INVALID_GRPC_CERTIFICATE_HASH; case MISSING_EXPIRY_TIME -> MISSING_EXPIRY_TIME; + case NO_SCHEDULING_ALLOWED_AFTER_SCHEDULED_RECURSION -> NO_SCHEDULING_ALLOWED_AFTER_SCHEDULED_RECURSION; + case RECURSIVE_SCHEDULING_LIMIT_REACHED -> RECURSIVE_SCHEDULING_LIMIT_REACHED; + case WAITING_FOR_LEDGER_ID -> WAITING_FOR_LEDGER_ID; + case MAX_ENTRIES_FOR_FEE_EXEMPT_KEY_LIST_EXCEEDED -> MAX_ENTRIES_FOR_FEE_EXEMPT_KEY_LIST_EXCEEDED; + case FEE_EXEMPT_KEY_LIST_CONTAINS_DUPLICATED_KEYS -> FEE_EXEMPT_KEY_LIST_CONTAINS_DUPLICATED_KEYS; + case INVALID_KEY_IN_FEE_EXEMPT_KEY_LIST -> INVALID_KEY_IN_FEE_EXEMPT_KEY_LIST; + case INVALID_FEE_SCHEDULE_KEY -> INVALID_FEE_SCHEDULE_KEY; + case FEE_SCHEDULE_KEY_CANNOT_BE_UPDATED -> FEE_SCHEDULE_KEY_CANNOT_BE_UPDATED; + case FEE_SCHEDULE_KEY_NOT_SET -> FEE_SCHEDULE_KEY_NOT_SET; + case MAX_CUSTOM_FEE_LIMIT_EXCEEDED -> MAX_CUSTOM_FEE_LIMIT_EXCEEDED; + case NO_VALID_MAX_CUSTOM_FEE -> NO_VALID_MAX_CUSTOM_FEE; + case INVALID_MAX_CUSTOM_FEES -> INVALID_MAX_CUSTOM_FEES; + case DUPLICATE_DENOMINATION_IN_MAX_CUSTOM_FEE_LIST -> DUPLICATE_DENOMINATION_IN_MAX_CUSTOM_FEE_LIST; + case DUPLICATE_ACCOUNT_ID_IN_MAX_CUSTOM_FEE_LIST -> DUPLICATE_ACCOUNT_ID_IN_MAX_CUSTOM_FEE_LIST; + case MAX_CUSTOM_FEES_IS_NOT_SUPPORTED -> MAX_CUSTOM_FEES_IS_NOT_SUPPORTED; case UNRECOGNIZED -> // NOTE: Protobuf deserialization will not give us the code on the wire throw new IllegalArgumentException( diff --git a/sdk/src/main/java/com/hedera/hashgraph/sdk/SystemDeleteTransaction.java b/sdk/src/main/java/com/hedera/hashgraph/sdk/SystemDeleteTransaction.java index 0c0335760..7838817fe 100644 --- a/sdk/src/main/java/com/hedera/hashgraph/sdk/SystemDeleteTransaction.java +++ b/sdk/src/main/java/com/hedera/hashgraph/sdk/SystemDeleteTransaction.java @@ -16,6 +16,9 @@ import javax.annotation.Nullable; /** + * @deprecated + * This transaction is obsolete, not supported, and SHALL fail with a + * pre-check result of `NOT_SUPPORTED`. * Delete a file or smart contract - can only be done with a Hedera admin. *

* When it is deleted, it immediately disappears from the system as seen by the user, @@ -26,6 +29,7 @@ * When a smart contract is deleted, the cryptocurrency account within it continues * to exist, and is not affected by the expiration time here. */ +@Deprecated public final class SystemDeleteTransaction extends Transaction { @Nullable private FileId fileId = null; diff --git a/sdk/src/main/java/com/hedera/hashgraph/sdk/SystemUndeleteTransaction.java b/sdk/src/main/java/com/hedera/hashgraph/sdk/SystemUndeleteTransaction.java index bb2a8a36f..5060d0760 100644 --- a/sdk/src/main/java/com/hedera/hashgraph/sdk/SystemUndeleteTransaction.java +++ b/sdk/src/main/java/com/hedera/hashgraph/sdk/SystemUndeleteTransaction.java @@ -15,10 +15,14 @@ import javax.annotation.Nullable; /** + * @deprecated + * This transaction is obsolete, not supported, and SHALL fail with a + * pre-check result of `NOT_SUPPORTED`. * Undelete a file or smart contract that was deleted by AdminDelete. *

* Can only be done with a Hedera admin. */ +@Deprecated public final class SystemUndeleteTransaction extends Transaction { @Nullable private FileId fileId; diff --git a/sdk/src/main/proto/account.proto b/sdk/src/main/proto/account.proto index 3c7cfce55..1e06e306f 100644 --- a/sdk/src/main/proto/account.proto +++ b/sdk/src/main/proto/account.proto @@ -1,13 +1,26 @@ +/** + * # Account. + * This is a single account within the Hedera network. An Account is the + * primary entity representing ownership of assets tracked on the ledger. + * Account Allowances are also described here, and these represent permission + * granted to an account to transfer assets owned by a different account which + * granted the "allowance". Allowances specify the assets and amounts which may + * be transferred. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,10 +32,8 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ -import "common.proto"; import "basic_types.proto"; option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -30,224 +41,554 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** - * Representation of a Hedera Token Service account entity in the network Merkle tree. + * A single Account in the Hedera distributed ledger. + * + * Each Account SHALL have a unique three-part identifier, a Key, and one + * or more token balances.
+ * Each Account SHALL have an alias, which has multiple forms, and MAY be set automatically.
+ * Several additional items SHALL be associated with the Account to enable + * full functionality.
+ * Assets SHALL be represented as linked-lists with only the "head" item + * referenced directly in the Account, and the remaining items SHALL be + * accessible via the token relation or unique tokens maps.
+ * Accounts, as most items in the network, SHALL have an expiration time, + * recorded as seconds since the epoch, and MUST be "renewed" for a small fee + * at expiration. This helps to reduce the amount of inactive accounts retained + * in state.
+ * Another account MAY be designated to pay any renewal fees and automatically + * renew an account for (by default) 30-90 days at a time as a means to + * optionally ensure important accounts remain active.
+ * Accounts MAY participate in securing the network by "staking" the account + * balances to a particular network node, and receive a portion of network + * fees as a reward. An account MAY optionally decline these rewards but still + * stake its balances.
+ * An account MAY optionally require that inbound transfer transactions be + * signed by that account as receiver + * (in addition to the sender's signature).
+ * As with all network entities, Account ID SHALL be represented as + * shard.realm.X.
+ * Alias and contractId SHALL be additional identifiers used to connect accounts + * to transactions before the account is fully enabled, + * or in EVM contracts.
+ * + * --- * - * As with all network entities, account has a unique entity number represented as shard.realm.X. - * X can be an alias public key or an EVM address or a number. + * #### Alias + * There is considerable complexity with `alias` (aka `evm_address`) for + * Accounts. Much of this comes from the existence of a "hidden" alias for + * almost all accounts, and the reuse of the alias field for both EVM reference + * and "automatic" account creation. + * + * For the purposes of this specification, we will use the following terms for + * clarity. + * - `key_alias` is the account public key as a protobuf serialized message + * and used for auto-creation and subsequent lookup. This is only valid if + * the account key is a + * single `primitive` key, either ED25519 or ECDSA_SECP256K1. + * - `evm_address` exists for every account and is one of + * - `contract_address`, which is the 20 byte EVM contract address per + * EIP-1014 + * - `evm_key_address`, which is the keccak-256 hash of a ECDSA_SECP256K1 + * `primitive` key. + * - This is for accounts lazy-created from EVM public keys, when the + * corresponding ECDSA_SECP256K1 public key is presented in a + * transaction signed by the private key for that public key, the + * account is created that key assigned, and the protobuf-serialized + * form is set as the account alias. + * - `long_zero`, is a synthetic 20 byte address inferred for "normally" + * created accounts. It is constructed from the "standard" AccountID as + * follows. + * - 4 byte big-endian shard number + * - 8 byte big-endian realm number + * - 8 byte big-endian entity number + * + * The `alias` field in the `Account` message SHALL contain one of four values + * for any given account. + * - The `key_alias`, if the account was created by transferring HBAR to the + * account referenced by `key_alias`. + * - The `evm_key_address` if the account was created from an EVM public key + * - The `contract_address` if the account belongs to an EVM contract + * - Not-Set/null/Bytes.EMPTY (collectively `null`) if the account was + * created normally + * + * If the `alias` field of an `Account` is any form of `null`, then the account + * MAY be referenced by `alias` in an `AccountID` by using the `long_zero` + * address for the account. This "hidden default" alias SHALL NOT be stored, + * but is synthesized by the node software as needed, and may be synthesized by + * an EVM contract or client software as well. + * + * An AccountID in a transaction MAY reference an `Account` with + * `shard`.`realm`.`alias`.
+ * If the account `alias` field is set for an Account, that value SHALL be the + * account alias.
+ * If the account `alias` field is not set for an Account, the `long_zero` + * alias SHALL be the account alias. */ - message Account { /** - * The unique entity id of the account. + * The unique ID of this account. + *

+ * An account ID, when assigned to this field, SHALL be of + * the form `shard.realm.number`.
+ * Transactions MAY reference the account by alias, but the account itself + * MUST always have a purely numeric identifier. This numeric ID is the + * value used to reference the account in query responses, transaction + * receipts, transaction records, and the block stream. */ AccountID account_id = 1; + /** - * The alias to use for this account, if any. + * An account EVM alias. + *

+ * This is a value used in some contexts to reference an account when the + * numeric account identifier is not available.
+ * This field, when set to a non-default value, is immutable and + * SHALL NOT be changed. */ bytes alias = 2; + /** - * (Optional) The key to be used to sign transactions from the account, if any. - * This key will not be set for hollow accounts until the account is finalized. - * This key should be set on all the accounts, except for immutable accounts (0.0.800 and 0.0.801). + * The key to be used to sign transactions from this account, if any. + *

+ * This key SHALL NOT be set for hollow accounts until the account + * is finalized.
+ * This key SHALL be set on all other accounts, except for certain + * immutable accounts (0.0.800 and 0.0.801) necessary for network function + * and otherwise secured by the governing council. */ Key key = 3; + /** - * The expiration time of the account, in seconds since the epoch. + * The current expiration time of this account, in seconds since the epoch. + *

+ * For this purpose, `epoch` SHALL be the UNIX epoch + * with 0 at `1970-01-01T00:00:00.000Z`.
+ * This account SHALL be due standard renewal fees when the network + * consensus time exceeds this time.
+ * If rent and expiration are enabled for the network, and automatic + * renewal is enabled for this account, renewal fees SHALL be charged + * after this time, and, if charged, the expiration time SHALL be + * extended for another renewal period.
+ * This account MAY be expired and removed from state at any point + * after this time if not renewed.
+ * An account holder MAY extend this time by submitting an account + * update transaction to modify expiration time, subject to the current + * maximum expiration time for the network. */ int64 expiration_second = 4; + /** - * The balance of the account, in tiny-bars. + * The HBAR balance of this account, in tinybar (10-8 HBAR). + *

+ * This value is a signed integer for efficiency, but MUST always + * be a whole number. */ int64 tinybar_balance = 5; + /** - * An optional description of the account with UTF-8 encoding up to 100 bytes. + * A short description of this account. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 6; + /** - * A boolean marking if the account has been deleted. + * A boolean indicating that this account is deleted. */ bool deleted = 7; + /** - * The amount of hbars staked to the account. + * The amount of HBAR staked to this account by others. */ int64 staked_to_me = 8; + /** - * If this account stakes to another account, its value will be -1. It will - * be set to the time when the account starts staking to a node. + * If this account stakes to another account, this value SHALL be set to + * the time when the current period for staking and reward + * calculations began. */ int64 stake_period_start = 9; + // Below comment is NOT included in generated documentation /** - * ID of the account or node to which this account is staking. + * ID of the account or node to which this account is staking, if any. + *

+ * if not set this field MAY be interpreted as staked_account_id + * with value `0.0.0`. */ oneof staked_id { /** - * ID of the new account to which this account is staking. If set to the sentinel 0.0.0 AccountID, - * this field removes this account's staked account ID. + * An identifier for the account to which this account is + * staking its balances as a proxy. + *

+ * If this account is not currently staking its balances, then this + * field, if set, SHALL be the sentinel value of `0.0.0`. */ AccountID staked_account_id = 10; /** - * ID of the new node this account is staked to. If set to the sentinel -1, this field - * removes this account's staked node ID. + * An identifier for the node this account is staked to. + *

+ * If this account is not currently staking its balances, then this + * field, if set, SHALL be the sentinel value of `-1`. + * Wallet software SHOULD surface staking issues to users and provide a + * simple mechanism to update staking to a new node ID in the event the + * prior staked node ID ceases to be valid. + *

+ *

Note: node IDs do fluctuate as node operators change. + * The Account owner MUST submit a new transaction to change this value + * if the current node ID changes or ceases to operate as a node. An + * account with an invalid `staked_node_id` SHALL NOT participate in + * staking until the `staked_node_id` is updated to a valid node ID. + *
*/ int64 staked_node_id = 11; } + /** - * A boolean marking if the account declines rewards. + * A boolean indicating that this account has chosen to decline rewards for + * staking its balances. + *

+ * This account MAY still stake its balances, but SHALL NOT receive reward + * payments for doing so. */ bool decline_reward = 12; + /** - * A boolean marking if the account requires a receiver signature. + * A boolean indicating that the account requires a receiver signature for + * inbound token transfer transactions. + *

+ * If this value is `true` then a transaction to transfer tokens to this + * account SHALL NOT succeed unless this account has signed the transfer + * transaction. */ bool receiver_sig_required = 13; + /** - * The token ID of the head of the linked list from token relations map for the account. + * A token ID at the head of the linked list for this account from the + * token relations map.
+ * The token relations are connected by including the "next" and "previous" + * TokenID in each TokenRelation message. The "head" item in that list is + * found by looking up the TokenRelation with this Account's account_id and + * this head_token_id. Each subsequent item in the list is found via + * similar lookup with both an AccountID and a TokenID. */ TokenID head_token_id = 14; + /** - * The NftID of the head of the linked list from unique tokens map for the account. + * A NftID at the head of the linked list for this account from + * the unique tokens map.
+ * The unique token relations are connected by including the "next" and + * "previous" NftID in each Nft message. The "head" item in that list is + * found by looking up the Nft with ID matching this head_nft_id. Each + * subsequent item in the list is found via similar lookup with the next + * or previous NftID. */ NftID head_nft_id = 15; + /** - * The serial number of the head NftID of the linked list from unique tokens map for the account. - */ + * A serial number in the NftID at the head of the linked list for this + * account from unique tokens map. + *

+ * This MUST match the `serial_number` field of `head_nft_id`. + */ int64 head_nft_serial_number = 16; + /** - * The number of NFTs owned by the account. + * A number of non-fungible tokens (NTFs) owned by the account. */ int64 number_owned_nfts = 17; + /** - * The maximum number of tokens that can be auto-associated with the account. + * A maximum for the number of tokens that can be automatically + * associated with this account. + *

+ * If this is less than or equal to `used_auto_associations` (or 0), then + * this account MUST manually associate with a token before transacting in + * that token.
+ * This value may also be `-1` to indicate no limit.
+ * This value MUST NOT be less than `-1`. */ int32 max_auto_associations = 18; + /** - * The number of used auto-association slots. + * A count of used auto-association slots. + *

+ * If this is greater than, or equal to, the current value of + * `max_auto_associations`, then this account MUST manually associate with + * a new token before transacting in that token. */ int32 used_auto_associations = 19; + /** - * The number of tokens associated with the account. This number is used for - * fee calculation during renewal of the account. + * A count of tokens associated with this account. + *

+ * This value determines a portion of the renewal fee for this account. */ int32 number_associations = 20; + /** - * A boolean marking if the account is a smart contract. + * A boolean indicating that this account is owned by a smart contract. */ bool smart_contract = 21; + /** - * The number of tokens with a positive balance associated with the account. - * If the account has positive balance in a token, it can not be deleted. + * A count of tokens with a positive balance associated with this account. + *

+ * If the account has a positive balance in any token, + * it SHALL NOT be deleted. */ int32 number_positive_balances = 22; + /** - * The nonce of the account, used for Ethereum interoperability. + * A nonce of this account for Ethereum interoperability. */ int64 ethereum_nonce = 23; + /** - * The amount of hbars staked to the account at the start of the last rewarded period. + * An amount of HBAR staked by this account at the start of + * the last reward period. */ int64 stake_at_start_of_last_rewarded_period = 24; + /** - * (Optional) The id of an auto-renew account, in the same shard and realm as the account, that - * has signed a transaction allowing the network to use its balance to automatically extend the account's - * expiration time when it passes. + * An account identifier for automatic renewal.
+ * This is the identifier of another account, in the same shard and + * realm as this account, that has signed a transaction allowing the + * network to use its balance, if needed, to automatically extend this + * account's expiration time during automatic renewal processing. + *

+ * If this is set, and this account lack sufficient HBAR balance to pay + * renewal fees when due, then the network SHALL deduct the necessary fees + * from the designated auto renew account, if that account has sufficient + * balance. */ AccountID auto_renew_account_id = 25; + /** - * The number of seconds the network should automatically extend the account's expiration by, if the - * account has a valid auto-renew account, and is not deleted upon expiration. - * If this is not provided in an allowed range on account creation, the transaction will fail with INVALID_AUTO_RENEWAL_PERIOD. - * The default values for the minimum period and maximum period are 30 days and 90 days, respectively. + * A count of the number of seconds to extend this account's expiration. + *

+ * The network SHALL extend the account's expiration by this number of + * seconds, if funds are available, upon automatic renewal.
+ * This SHALL NOT apply if the account is already deleted + * upon expiration.
+ * If this is not provided in an allowed range on account creation, the + * transaction SHALL fail with INVALID_AUTO_RENEWAL_PERIOD. The default + * values for the minimum period and maximum period are currently 30 days + * and 90 days, respectively. */ int64 auto_renew_seconds = 26; + /** - * If this account is a smart-contract, number of key-value pairs stored on the contract. - * This is used to determine the storage rent for the contract. + * A count of smart contract key-value pairs.
+ * If this account is a smart-contract, this is the number of key-value + * pairs stored on the contract. + *

+ * If this account is not a smart contract, this field + * SHALL NOT be used.
+ * This value SHALL determine a portion of the storage rental + *fees for the contract. */ int32 contract_kv_pairs_number = 27; + /** - * (Optional) List of crypto allowances approved by the account. - * It contains account number for which the allowance is approved to and - * the amount approved for that account. + * A list of crypto (HBAR) allowances approved by this account. + *

+ * If this is not empty, each allowance SHALL permit a specified "spender" + * account to spend this account's HBAR balance, up to a designated + * limit.
+ * This field SHALL permit spending only HBAR balance, not other tokens the + * account may hold. Allowances for other tokens SHALL be listed in the + * `token_allowances` field or the `approve_for_all_nft_allowances` field. */ repeated AccountCryptoAllowance crypto_allowances = 28; + /** - * (Optional) List of non-fungible token allowances approved for all by the account. - * It contains account number approved for spending all serial numbers for the given - * NFT token number using approved_for_all flag. - * Allowances for a specific serial number is stored in the NFT itself in state. + * A list of non-fungible token (NFT) allowances approved by this account. + *

+ * If this is not empty, each allowance permits a specified "spender" + * account to transfer _all_ of this account's non-fungible tokens from a + * particular collection.
+ * Allowances for a specific serial number MUST be directly associated with + * that specific non-fungible token, rather than the holding account. */ repeated AccountApprovalForAllAllowance approve_for_all_nft_allowances = 29; /** - * (Optional) List of fungible token allowances approved by the account. - * It contains account number for which the allowance is approved to and the token number. - * It also contains and the amount approved for that account. + * A list of fungible token allowances approved by this account. + *

+ * If this is not empty, each allowance permits a specified "spender" to + * spend this account's fungible tokens, of the designated type, up to a + * designated limit. */ repeated AccountFungibleTokenAllowance token_allowances = 30; + /** - * The number of tokens for which this account is treasury + * A count of tokens for which this account is the treasury account. + *

+ * Each native token is initially created with all tokens held by its + * treasury, and the owner of that account (which may be a smart contract) + * determines how those tokens are distributed. */ uint32 number_treasury_titles = 31; + /** - * A flag indicating if the account is expired and pending removal. - * Only the entity expiration system task toggles this flag when it reaches this account - * and finds it expired. Before setting the flag the system task checks if the account has - * an auto-renew account with balance. This is done to prevent a zero-balance account with a funded - * auto-renew account from being treated as expired in the interval between its expiration - * and the time the system task actually auto-renews it. + * A flag indicating that the account is expired and pending removal. + *

+ * When the network checks for entity expiration, it SHALL set this flag if + * the account expiration time has past and the account has no HBAR + * sufficient to pay current renewal fees.
+ * If the account has an auto-renew account set with an HBAR balance that + * could pay for an auto-renewal, then this flag SHALL NOT be set. This + * ensures the account is not encumbered during the time between expiration + * and when the auto-renewal processing renews the account. */ bool expired_and_pending_removal = 32; + /** - * The first key in the doubly-linked list of this contract's storage mappings; - * It will be null if if the account is not a contract or the contract has no storage mappings. + * A contract storage key.
+ * This is the first key in the doubly-linked list of this + * contract's storage mappings. + *

+ * This value SHALL be empty if the account is not a contract or the + * contract has no storage mappings. */ bytes first_contract_storage_key = 33; /** - * A pending airdrop ID at the head of the linked list for this account - * from the account airdrops map.
- * The account airdrops are connected by including the "next" and "previous" - * `PendingAirdropID` in each `AccountAirdrop` message. + * A pending airdrop ID.
+ * This is the head of the linked list for this account from the + * account airdrops map.
*

+ * The account airdrops SHALL be connected by including the "next" and + * "previous" `PendingAirdropID` in each `AccountAirdrop` message.
* This value SHALL NOT be empty if this account is "sender" for any * pending airdrop, and SHALL be empty otherwise. */ PendingAirdropId head_pending_airdrop_id = 34; /** - * The number of pending airdrops owned by the account. This number is used to collect rent - * for the account. + * A number of pending airdrops. + *

+ * This count SHALL be used to calculate rent _without_ walking the linked + * list of pending airdrops associated to this account via the + * `head_pending_airdrop_id` field.
+ * This value MUST be updated for every airdrop, clam, or cancel transaction + * that designates this account as a receiver.
+ * This number MUST always match the count of entries in the "list" + * identified by `head_pending_airdrop_id`. */ uint64 number_pending_airdrops = 35; } /** - * Allowance granted by this account to a spender for a specific non-fungible token - * using ApproveForAll. This allows spender to spend all serial numbers for the given - * non-fungible token id. + * Permission granted by one account (the "funding" account) to another account + * (the "spender" account) that allows the spender to transfer all serial + * numbers of a specific non-fungible token (NFT) collection owned by the + * funding account.
+ * This is a broad permission, as it does not matter how many NFTs of the + * specified collection the funding account owns, the spender MAY dispose of + * any or all of them with this allowance.
+ * Each token type (typically a collection of NFTs) SHALL require a separate + * allowance.
+ * Allowances for a specific serial number MUST be directly associated with + * that specific non-fungible token, rather than the holding account. + * + * An allowance SHALL NOT transfer any tokens directly, it only permits + * transactions signed only by the spender account to transfer any non-fungible + * tokens of the specified type owned by the funding account. */ message AccountApprovalForAllAllowance { + /** + * The identifier for the token associated with this allowance. + *

+ * This token MUST be a non-fungible/unique token. + */ TokenID token_id = 1; + + /** + * The identifier for the spending account associated with this allowance. + *

+ * This account SHALL be permitted to sign transactions to spend tokens of + * the associated token type from the funding/allowing account. + */ AccountID spender_id = 2; } /** - * Allowance granted by this account to another account for a specific fungible token. - * This also contains the amount of the token that is approved for the account. - * This allows spender to spend the amount of tokens approved for the account. + * Permission granted by one account (the "funding" account) to another account + * (the "spender" account) that allows the spender to spend a specified amount + * of a specific non-HBAR fungible token from the balance owned by the funding + * account. + * + * An allowance SHALL NOT transfer any tokens directly, it only permits + * transactions signed only by the spender account to transfer tokens of the + * specified type, up to the amount specified, from the funding account. + * + * Once the specified amount is spent, the allowance SHALL be consumed and a + * new allowance SHALL be required before that spending account may spend + * additional tokens from the funding account. */ message AccountFungibleTokenAllowance { + /** + * The identifier for the token associated with this allowance. + *

+ * This token MUST be a fungible/common token. + */ TokenID token_id = 1; + + /** + * The identifier for the spending account associated with this allowance. + *

+ * This account SHALL be permitted to sign transactions to spend tokens of + * the associated token type from the funding/allowing account.
+ * This permission SHALL be limited to no more than the specified `amount`. + */ AccountID spender_id = 2; + + /* + * The maximum amount that the spender account may transfer within the + * scope of this allowance. + *

+ * This allowance SHALL be consumed if any combination of transfers + * authorized via this allowance meet this value in total.
+ * This value MUST be specified in the smallest units of the relevant token + * (i.e. 10-decimals whole tokens). + */ int64 amount = 3; } /** - * Allowance granted by this account to another account for an amount of hbars. - * This allows spender to spend the amount of hbars approved for the account. + * Permission granted by one account (the "funding" account) to another account + * (the "spender" account) that allows the spender to spend a specified amount + * of HBAR owned by the funding account. + * + * An allowance SHALL NOT transfer any HBAR directly, it only permits + * transactions signed only by the spender account to transfer HBAR, up to the + * amount specified, from the funding account. + * + * Once the specified amount is spent, the allowance SHALL be consumed and a + * new allowance SHALL be required before that spending account may spend + * additional HBAR from the funding account. */ message AccountCryptoAllowance { + /** + * The identifier for the spending account associated with this allowance. + *

+ * This account SHALL be permitted to sign transactions to spend HBAR from + * the funding/allowing account.
+ * This permission SHALL be limited to no more than the specified `amount`. + */ AccountID spender_id = 1; + + /* + * The maximum amount that the spender account may transfer within the + * scope of this allowance. + *

+ * This allowance SHALL be consumed if any combination of transfers + * authorized via this allowance meet this value in total.
+ * This value MUST be specified in tinybar (i.e. 10-8 HBAR). + */ int64 amount = 2; } diff --git a/sdk/src/main/proto/account_pending_airdrop.proto b/sdk/src/main/proto/account_pending_airdrop.proto index 6b2c7b47b..d219e49e1 100644 --- a/sdk/src/main/proto/account_pending_airdrop.proto +++ b/sdk/src/main/proto/account_pending_airdrop.proto @@ -1,3 +1,14 @@ +/** + * # Account Pending Airdrop. + * A single pending airdrop awaiting claim by the recipient. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; @@ -36,35 +47,36 @@ option java_multiple_files = true; * The pending airdrop MUST NOT be canceled.
* The pending airdrop `sender` account's `head_pending_airdrop_id` field * MUST match the `pending_airdrop_id` field in this message. - * - * ### Record Stream Effects - * This value is not currently published in the record stream. */ message AccountPendingAirdrop { - /** - * The value of the current airdrop id. SHALL NOT be set for non fungible tokens - */ - PendingAirdropValue pending_airdrop_value = 1; + /** + * An amount of fungible tokens to be sent for this pending airdrop. + *

+ * This field SHALL NOT be set for non-fungible/unique tokens. + */ + PendingAirdropValue pending_airdrop_value = 1; - /** - * A pending airdrop identifier.
- * This identifies the specific pending airdrop that precedes this position - * within the doubly linked list of pending airdrops "owed" by the sending - * account associated with this account airdrop "list". - *

- * This SHALL match `pending_airdrop_id` if this is the only entry - * in the "list". - */ - PendingAirdropId previous_airdrop = 2; + /** + * A pending airdrop identifier. + *

+ * This field SHALL identify the specific pending airdrop that + * precedes this position within the doubly linked list of pending + * airdrops "owed" by the sending account associated with this + * account airdrop "list".
+ * This SHALL match `pending_airdrop_id` if this is the only entry + * in the "list". + */ + PendingAirdropId previous_airdrop = 2; - /** - * A pending airdrop identifier.
- * This identifies the specific pending airdrop that follows this position - * within the doubly linked list of pending airdrops "owed" by the sending - * account associated with this account airdrop "list". - *

- * This SHALL match `pending_airdrop_id` if this is the only entry - * in the "list". - */ - PendingAirdropId next_airdrop = 3; + /** + * A pending airdrop identifier.
+ *

+ * This field SHALL identify the specific pending airdrop that + * follows this position within the doubly linked list of pending + * airdrops "owed" by the sending account associated with this + * account airdrop "list".
+ * This SHALL match `pending_airdrop_id` if this is the only entry + * in the "list". + */ + PendingAirdropId next_airdrop = 3; } diff --git a/sdk/src/main/proto/address_book_service.proto b/sdk/src/main/proto/address_book_service.proto index d3cde5733..9321153b0 100644 --- a/sdk/src/main/proto/address_book_service.proto +++ b/sdk/src/main/proto/address_book_service.proto @@ -1,3 +1,14 @@ +/** + * # Address Book Service API + * GRPC service definitions for the Hedera Address Book Service (HABS). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; @@ -21,8 +32,6 @@ package proto; option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package -import "query.proto"; -import "response.proto"; import "transaction_response.proto"; import "transaction.proto"; @@ -38,9 +47,9 @@ import "transaction.proto"; * * ### For a node creation transaction. * - The node operator SHALL create a `createNode` transaction. - * - The node operator SHALL sign this transaction with the active `key` for - * the account to be assigned as the "node account". - * - The node operator MUST deliver the signed transaction to the Hedera + * - The node operator MUST sign this transaction with the `Key` + * set as the `admin_key` for the new `Node`. + * - The node operator SHALL deliver the signed transaction to the Hedera * council representative. * - The Hedera council representative SHALL arrange for council members to * review and sign the transaction. @@ -50,8 +59,8 @@ import "transaction.proto"; * - Upon receipt of a valid and signed node creation transaction the network * software SHALL * - Validate the threshold signature for the Hedera governing council - * - Validate the signature of the active `key` for the account to be - * assigned as the "node account". + * - Validate the signature of the `Key` provided as the new `admin_key` + * for the `Node`. * - Create the new node in state, this new node SHALL NOT be active in the * network at this time. * - When executing the next `freeze` transaction with `freeze_type` set to @@ -63,8 +72,8 @@ import "transaction.proto"; * - The node operator or Hedera council representative SHALL create a * `deleteNode` transaction. * - If the node operator creates the transaction - * - The node operator MUST sign this transaction with the active `key` - * for the account assigned as the "node account". + * - The node operator MUST sign this transaction with the `Key` + * set as the `admin_key` for the existing `Node`. * - The node operator SHALL deliver the signed transaction to the Hedera * council representative. * - The Hedera council representative SHALL arrange for council members to @@ -74,7 +83,7 @@ import "transaction.proto"; * network. * - Upon receipt of a valid and signed node deletion transaction the network * software SHALL - * - Validate the threshold signature for the Hedera governing council + * - Validate the signature for the Hedera governing council * - Remove the existing node from network state. The node SHALL still * be active in the network at this time. * - When executing the next `freeze` transaction with `freeze_type` set to @@ -107,7 +116,7 @@ import "transaction.proto"; */ service AddressBookService { /** - * A transaction to create a new consensus node in the network. + * A transaction to create a new consensus node in the network * address book. *

* This transaction, once complete, SHALL add a new consensus node to the diff --git a/sdk/src/main/proto/basic_types.proto b/sdk/src/main/proto/basic_types.proto index 282890f95..d7e65a698 100644 --- a/sdk/src/main/proto/basic_types.proto +++ b/sdk/src/main/proto/basic_types.proto @@ -1,13 +1,45 @@ +/** + * # Basic Types + * Fundamental message types used across transactions and state as field types. + * + * ### Requirements for identifier values + * - Most entities in the network SHALL be identified by a multi-part + * identifier. These identifier values SHALL consist of a shard, a realm, and + * an entity identifier. + * - Shard, Realm, and Entity Number MUST all be whole numbers. + * - A Shard SHALL be globally unique. + * - A Realm MAY be reused between shards, but SHALL be unique within a shard. + * - An Entity Number MAY be reused between shards and realms, but SHALL be + * unique within each combination of shard and realm. + * - Every object (e.g. account, file, token, etc...) SHALL be scoped to exactly + * one realm and shard. Thus a File has a FileID, a numeric triplet, such as + * 0.0.2 for shard 0, realm 0, entity 2. + * - Identifier values SHOULD use an Entity Number as the third component of the + * identifier. Some, however, MAY use alternative or composite values for the + * Entity portion of the three part identifier. Any such alternative or + * composite value MUST be unique within that shard and realm combination. + * - The entity portion of the identifier, regardless of type, MUST be unique + * within that realm and shard combination and MAY be globally unique. + * - The triplet of shard.realm.entity MUST be globally unique, even across + * different identifier types. + * - Each realm SHALL maintain a single counter for entity numbers, so if there + * is an identifier with value 0.1.2, then there MUST NOT be an identifier + * with value 0.1.2 for any other object. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2022 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +51,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ import "timestamp.proto"; @@ -30,42 +61,60 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; 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. + * A shard identifier.
+ * A shard is a partition of nodes running the network that processes + * transactions separately from other shards. Each shard is effectively an + * independent instance of the overall network that shares the same virtual + * distributed ledger, and may gossip cross-shard transactions with other + * shards to maintain overall correct processing of the ledger. */ message ShardID { /** - * the shard number (nonnegative) + * A whole number shard identifier. */ 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. + * A realm identifier.
+ * Within a given shard, every realm has a unique numeric identifier. + * Each account, file, and contract instance belongs to exactly one realm. */ message RealmID { /** - * The shard number (nonnegative) + * A whole number shard identifier. */ int64 shardNum = 1; /** - * The realm number (nonnegative) + * A whole number realm identifier. */ int64 realmNum = 2; } +/** + * Unique identifier for a token.
+ * As with all entity identifiers within the network, a token identifier + * consists of a combination of shard number, realm number, and entity number. + * Each of these numbers is unique within its scope (shard > realm > entity). + */ +message TokenID { + /** + * A whole number shard identifier. + */ + int64 shardNum = 1; + + /** + * A whole number realm identifier. + */ + int64 realmNum = 2; + + /** + * A whole number token identifier. + */ + int64 tokenNum = 3; +} + /** * A specific hash algorithm. * @@ -90,422 +139,626 @@ enum BlockHashAlgorithm { } /** - * The ID for an a cryptocurrency account + * A unique identifier for an Hedera account. + * + * An account identifier is of the form `shard.realm.[number|alias]`.
+ * The identifier MAY use the alias form when transferring HBAR to a public key + * before the account for that key is created, when only the alias value is + * known, or in some smart contracts that use the EVM address style alias to + * refer to Accounts.
+ * When the account entry is completed, the alias SHALL be stored separately in + * the Account record, and the identifier in the Account SHALL use the + * `accountNum` form. + * + * --- + * ### Additional Notes + * + * #### Alias + * There is considerable complexity with `alias` (aka `evm_address`) for + * Accounts. Much of this comes from the existence of a "hidden" alias for + * almost all accounts, and the reuse of the alias field for both EVM reference + * and "automatic" account creation.
+ * For the purposes of this specification, we will use the following terms for + * clarity. + * - `key_alias`
+ * The account public key as a protobuf serialized message and used for + * auto-creation and subsequent lookup. This is only valid if the account + * key is a single `primitive` key, either Ed25519 or ECDSA_SECP256K1. + * - `evm_address`
+ * Exists for every account and is one of + * - `contract_address`
+ * The 20 byte EVM address prescribed by `CREATE` or `CREATE2` + * - `evm_key_address`
+ * An arbitrary 20 byte EVM address that, for a usable externally owned + * account (EOA) SHALL be the rightmost 20 bytes of the Keccak-256 hash + * of a ECDSA_SECP256K1 key.
+ * Such accounts may be created in one of three ways: + * - Sending hbar or fungible tokens to an unused + * ECDSA_SECP256K1 key alias. + * - Sending hbar or fungible tokens to an unassigned 20-byte + * EVM address. + * - Submitting a `CryptoCreate` signed with the corresponding + * private key. + * - `long_zero`
+ * A synthetic 20 byte address inferred for "normally" created accounts. + * It is constructed from the "standard" AccountID as follows. + * 1. 4 byte big-endian shard number + * 1. 8 byte big-endian realm number + * 1. 8 byte big-endian entity number
+ * + * The `alias` field in the `Account` message SHALL contain one of four values + * for any given account. + * - The `key_alias`, if the account was created by transferring HBAR to the + * `key_alias` public key value. + * - The `evm_key_address` if the account was created from an EVM public key + * - The `contract_address` if the account belongs to an EVM contract + * - Not-Set/null/Bytes.EMPTY (collectively `null`) if the account was + * created normally + * + * If the `alias` field of an `Account` is any form of `null`, then the account + * MAY be referred to by `alias` in an `AccountID` by using the `long_zero` + * address for the account.
+ * This "hidden default" alias SHALL NOT be stored, but is synthesized by the + * node software as needed, and may be synthesized by an EVM contract or client + * software as well. + * + * --- + * + * #### Alias forms + * An `AccountID` in a transaction MAY reference an `Account` with + * `shard.realm.alias`.
+ * If the account `alias` field is set for an Account, that value SHALL be the + * account alias.
+ * If the account `alias` field is not set for an Account, the `long_zero` alias + * SHALL be the account alias. */ message AccountID { /** - * The shard number (nonnegative) + * A whole number shard identifier. */ int64 shardNum = 1; /** - * The realm number (nonnegative) + * A whole number realm identifier. */ int64 realmNum = 2; - /** - * The account number unique within its realm which can be a non-negative integer, an alias public key or an EVM address. - * For any AccountID fields in the query response, transaction record or transaction receipt only accountNum will - * be populated. - */ oneof account { /** - * A non-negative account number unique within its realm + * A whole number account number, unique within its realm and shard. + *

+ * For any AccountID fields in the query response, transaction records, + * transaction receipts, or block stream `accountNum` MUST be used. */ int64 accountNum = 3; /** - * The public key bytes to be used as the account's alias. The public key bytes are the result of serializing - * a protobuf Key message for any primitive key type. Currently only primitive key bytes are supported as an alias - * (ThresholdKey, KeyList, ContractID, and delegatable_contract_id are not supported) - * - * May also be the ethereum account 20-byte EVM address to be used initially in place of the public key bytes. This EVM - * address may be either the encoded form of the shard.realm.num or the keccak-256 hash of a ECDSA_SECP256K1 primitive key. - * - * At most one account can ever have a given alias and it is used for account creation if it - * was automatically created using a crypto transfer. It will be null if an account is created normally. - * It is immutable once it is set for an account. - * - * If a transaction auto-creates the account, any further transfers to that alias will simply be deposited - * in that account, without creating anything, and with no creation fee being charged. - * - * If a transaction lazily-creates this account, a subsequent transaction will be required containing the public key bytes - * that map to the EVM address bytes. The provided public key bytes will then serve as the final alias bytes. + * An alias value.
+ * Alias is a value used in some contexts to refer to an account when + * account number is not available, and may be an alias public key, or + * an EVM address. */ bytes alias = 4; } } /** - * Identifier for a unique token (or "NFT"), used by both contract and token services. + * An identifier for a unique token (or "NFT"), used by both contract + * and token services. */ message NftID { /** - * The (non-fungible) token of which this NFT is an instance; uppercase for "ID" - * for backward compatibility with original definition of this field. + * A token identifier.
+ * This token represents the collection containing this NFT. */ TokenID token_ID = 1; /** - * The serial number of this NFT within its token type + * A unique serial number.
+ * This serial number is unique within its token type. */ int64 serial_number = 2; } /** - * The ID for a file + * An identifier for a File within the network. */ message FileID { /** - * The shard number (nonnegative) + * A whole number shard identifier. */ int64 shardNum = 1; /** - * The realm number (nonnegative) + * A whole number realm identifier. */ int64 realmNum = 2; /** - * A nonnegative File number unique within its realm + * A whole number file identifier, unique within its realm and shard. */ int64 fileNum = 3; } /** - * The ID for a smart contract instance + * An identifier for a smart contract within the network. */ message ContractID { /** - * The shard number (nonnegative) + * A whole number shard identifier. */ int64 shardNum = 1; /** - * The realm number (nonnegative) + * A whole number realm identifier. */ int64 realmNum = 2; oneof contract { /** - * A nonnegative number unique within a given shard and realm + * A whole number contract identifier, unique within its realm and shard. */ int64 contractNum = 3; /** - * The 20-byte EVM address of the contract to call. - * - * Every contract has an EVM address determined by its shard.realm.num id. - * This address is as follows: - *

    - *
  1. The first 4 bytes are the big-endian representation of the shard.
    2. - *
  2. The next 8 bytes are the big-endian representation of the realm.
    3. - *
  3. The final 8 bytes are the big-endian representation of the number.
    4. - *
- * - * Contracts created via CREATE2 have an additional, primary address that is - * derived from the EIP-1014 - * specification, and does not have a simple relation to a shard.realm.num id. - * - * (Please do note that CREATE2 contracts can also be referenced by the three-part - * EVM address described above.) + * A 20-byte EVM address of the contract to call. + *

+ * A contract created via a HAPI `ContractCreate` call SHALL have + * an EVM address determined by its `shard.realm.num` identifier.
+ * This address is as follows + *

    + *
  1. 4 byte big-endian shard number
    2. + *
  2. 8 byte big-endian realm number
    3. + *
  3. 8 byte big-endian contract number
    4. + *
+ * This address is not stored in state, but is computed when needed. + *

+ * Contracts created by any other means, including a HAPI + * `EthereumTransaction` whose `to` address is the zero address, + * SHALL have the EVM address prescribed by the `CREATE` or + * `CREATE2` opcode, as applicable. */ bytes evm_address = 4; } } /** - * 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 + * An unique identifier for a topic.
+ * Topics are part of the consensus service, messages are published to a topic. + */ +message TopicID { + /** + * A whole number shard identifier. + */ + int64 shardNum = 1; + + /** + * A whole number realm identifier. + */ + int64 realmNum = 2; + + /** + * A whole number topic identifier, unique within its realm and shard. + */ + int64 topicNum = 3; +} + +/** + * An unique identifier for a Schedule + */ +message ScheduleID { + /** + * A whole number shard + */ + int64 shardNum = 1; + + /** + * A whole number realm + */ + int64 realmNum = 2; + + /** + * A whole number schedule, unique within its realm and shard + */ + int64 scheduleNum = 3; +} + +/** + * A transaction identifier.
+ * This is used for retrieving receipts and records for a transaction + * and internally by the network for detecting when duplicate transactions are + * submitted. + * + * A transaction may be processed more reliably by submitting it to + * several 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 SHALL NOT be executed (and SHALL result in a + * `DUPLICATE_TRANSACTION` response).
+ * Multiple submission increase reliability on the assumption that an error in, + * for example, network connectivity will not affect all nodes equally. Latency + * might be slightly lower, if one node is handling intake significantly slower + * than others, for example. The base transaction fee is required for each + * submission, however, so the total fees charged are significantly higher when + * using this approach. + * + * ### Requirements + * Each transaction identifier MUST be unique.
+ * Multiple transactions MAY be submitted with the same transaction + * identifier, but all except the first SHALL be rejected as duplicate + * transactions.
+ * An identifier MUST specify a `payer` account to be charged all fees + * associated with the transaction.
+ * The `payer` account MUST exist and MUST have sufficient HBAR to pay all + * transaction fees.
+ * An identifier MUST specify a "valid start time".
+ * The "valid start time" MUST be strictly _earlier_ than the current + * network consensus time when submitted.
+ * The "valid start time" MUST NOT be more than `transaction.maxValidDuration` + * seconds before the current network consensus time when submitted.
+ * A client-submitted transaction MUST NOT set the `scheduled` flag. + * + * ### Additional Notes + * + * Additional items applicable to Scheduled Transactions: + * + * - The ID of a Scheduled Transaction, once executed, SHALL inherit both + * `transactionValidStart` and `accountID` from the `ScheduleCreate` + * transaction that created the schedule. + * - The `scheduled` property SHALL be set for Scheduled Transactions. */ message TransactionID { /** - * The transaction is invalid if consensusTimestamp < transactionID.transactionStartValid + * A timestamp for the transaction start time.
+ * This is the earliest expected start time for this transaction. + *

+ * This value MUST be strictly less than `consensusTimestamp` when the + * transaction is submitted. */ Timestamp transactionValidStart = 1; /** - * The Account ID that paid for this transaction + * An Account identifier. + *

+ * The identified account SHALL pay transaction fees for this transaction. */ AccountID accountID = 2; /** - * Whether the Transaction is of type Scheduled or no + * A scheduled transaction flag.
+ * If set, this transaction represents the execution of a Schedule after + * all necessary signatures are gathered. + *

+ * This flag MUST NOT be set in a user-submitted transaction. */ bool scheduled = 3; /** - * The identifier for an internal transaction that was spawned as part - * of handling a user transaction. (These internal transactions share the - * transactionValidStart and accountID of the user transaction, so a - * nonce is necessary to give them a unique TransactionID.) - * + * An identifier for an internal transaction.
+ * An internal transaction is one that was spawned as part of handling a + * user transaction. These internal transactions share the + * transactionValidStart and accountID of the user transaction, so a nonce + * is necessary to give them a unique TransactionID. + *

* An example is when a "parent" ContractCreate or ContractCall transaction * calls one or more HTS precompiled contracts; each of the "child" - * transactions spawned for a precompile has a id with a different nonce. + * transactions spawned for a precompile has a transaction id with a + * different nonce. + *

+ * This value MUST be unset for user-submitted transactions. */ int32 nonce = 4; } /** - * 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 token transfer. + * + * This message is only relevant to fungible/common token transfers. + * Non-fungible/unique (NFT) token transfers MUST use the NftTransfer message. */ message AccountAmount { /** - * The Account ID that sends/receives cryptocurrency or tokens + * An account identifier that will send or receive token(s). */ 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) + * An amount to send (negative) or receive (positive). + *

+ * This amount MUST be denominated in the smallest unit of the relevant + * token.
+ * For HBAR this SHALL be tinybar (10-8 HBAR).
+ * For other fungible/common tokens this SHALL depend on the value of + * `decimals` for that token. */ sint64 amount = 2; /** - * If true then the transfer is expected to be an approved allowance and the - * accountID is expected to be the owner. The default is false (omitted). + * An approved allowance flag.
+ * If true then the transfer is expected to be an approved allowance. + *

+ * If set, `accountID` SHALL be the owner that previously approved + * the allowance.
+ * The default value SHALL be false (unset). */ bool is_approval = 3; } /** - * 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. + * + * Each `AccountAmount` SHALL specify the account and the amount to + * send(negative) or receive(positive).
+ * Each `TransferList` SHALL be contained in another message that contains + * other details required to complete a transfer. This is typically a + * `CryptoTransferTransactionBody` or `TransactionRecord`.
+ * The `TransferList` SHALL only be used for HBAR transfers. Other token types + * MUST use the `TokenTransferList` message. */ message TransferList { /** - * Multiple list of AccountAmount pairs, each of which has an account and - * an amount to transfer into it (positive) or out of it (negative) + * A list of AccountAmount pairs.
+ * Each entry in this list is 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 NFT transfer.
+ * This refers to a sender account, a receiver account, and the serial number + * of an NFT to transfer from sender to receiver. + * + * Each `NftTransfer` SHALL be contained in another message (typically + * `TokenTransferList`) that details which `Token` type applies to this NFT + * transfer. */ message NftTransfer { /** - * The accountID of the sender + * An Account identifier for the sender. */ AccountID senderAccountID = 1; /** - * The accountID of the receiver + * An Account identifier for the receiver. */ AccountID receiverAccountID = 2; /** - * The serial number of the NFT + * A serial number for the NFT to transfer. */ int64 serialNumber = 3; /** - * If true then the transfer is expected to be an approved allowance and the - * senderAccountID is expected to be the owner. The default is false (omitted). + * An approved allowance flag.
+ * If true then the transfer is expected to be an approved allowance. + *

+ * If set, `senderAccountID` SHALL be the owner that previously approved + * the allowance.
+ * If set, the `senderAccountID` MUST be the "payer" account for + * the transaction
+ * The default value SHALL be false (unset). */ bool is_approval = 4; } /** - * 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 transfers for a particular (non-HBAR) token type. + * + * A `TokenTransferList` applies to a single token type, but may contain many + * individual transfers.
+ * Each transfer of a fungible/common token MUST specify an `accountID` and + * `amount`. Amount SHALL be positive when the account receives tokens, and + * SHALL be negative when the account sends tokens. The amount SHOULD NOT be + * `0`.
+ * In a transfer list containing fungible/common tokens in the `transfers` + * list, the sum of all such transfers MUST be zero (`0`). + * Each transfer of a unique token SHALL specify both sender and receiver, as + * well as the serial number transferred.
+ * A single `TokenTransferList` MUST contain `transfers` or `nftTransfers`, + * but MUST NOT contain both. */ message TokenTransferList { /** - * The ID of the token + * A token identifier.
+ * This is the token to be transferred. */ TokenID token = 1; /** - * Applicable to tokens of type FUNGIBLE_COMMON. Multiple list of AccountAmounts, each of which - * has an account and amount + * A list of account amounts. + *

+ * Each entry SHALL have an account and amount.
+ * These transfers SHALL be "double-entry" style; the credits (positive + * amount) and debits (negative amount) MUST sum to 0, unless this + * transfer list is part of a `mint` or `burn` operation.
+ * This SHALL be be set for fungible/common tokens and MUST be + * empty otherwise. */ 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 + * A list of NftTransfers. + *

+ * Each entry SHALL have a sender and receiver account, and the + * serial number of the unique token to transfer.
+ * This SHALL be be set for non-fungible/unique tokens and SHALL be + * empty otherwise. */ repeated NftTransfer nftTransfers = 3; /** - * If present, the number of decimals this fungible token type is expected to have. The transfer - * will fail with UNEXPECTED_TOKEN_DECIMALS if the actual decimals differ. + * An expected decimal precision.
+ * This is the number of decimals a fungible/common token type is + * _expected_ to have. + *

+ * The transfer SHALL fail with response code `UNEXPECTED_TOKEN_DECIMALS` + * if this is set and the actual decimals specified for the `Token` differ + * from this value.
+ * If `nftTransfers` is set, then this value SHOULD NOT be set. */ google.protobuf.UInt32Value expected_decimals = 4; } /** - * A rational number, used to set the amount of a value transfer to collect as a custom fee + * A rational number.
+ * A common use is to set the amount of a value transfer to collect as a + * custom fee. + * + * It is RECOMMENDED that both numerator and denominator be no larger than + * necessary to express the required fraction. A very large numerator, in + * particular, may not be reliable. + * Both fields are REQUIRED and SHOULD be positive integers. */ message Fraction { /** - * The rational's numerator + * A fractional number's numerator. */ int64 numerator = 1; /** - * The rational's denominator; a zero value will result in FRACTION_DIVIDES_BY_ZERO + * A fractional number's denominator. + *

+ * A zero value SHALL fail with response code `FRACTION_DIVIDES_BY_ZERO`. */ int64 denominator = 2; } -/** - * Unique identifier for a topic (used by the consensus service) - */ -message TopicID { - /** - * 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 - */ -message TokenID { - /** - * 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 - */ -message ScheduleID { - /** - * 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. Furthermore, tokens can have intrinsic or referential + * value, and can be whole and indivisible or fractional.
+ * These distinction might seem subtle, but it is important when considering + * how tokens can be traced, used, transferred, and if they can have isolated + * unique properties. + * + * A few examples (these may not match enumerations below) using IWA taxonomy. + *

+ *
fungible, whole, intrinsic, unique
+ *
Physical fiat currency
+ *
fungible, fractional, intrinsic, common
+ *
bank balance fiat currency
+ *
non-fungible, fractional, reference, unique
+ *
"mutual" collectible/art/property ownership
+ *
non-fungible, whole, intrinsic, unique
+ *
Physical work of fine art
+ *
non-fungible, whole, reference, unique
+ *
Registered property title
+ *
*/ 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. + * A fungible/common token.
+ * Tokens of this type are interchangeable with one another, where any + * quantity of tokens has the same value as another equal quantity, if + * they are in the same class. Tokens share a single set of properties, + * and are not distinct from one another. Ownership is represented as a + * balance or quantity associated to a given account. Tokens may be + * divided into fractional tokens, within reasonable limits. + *

+ * IWA taxonomy _fungible, fractional, intrinsic, common_ */ 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). + * A non-fungible/unique token.
+ * Tokens of this type are unique, and are not interchangeable with other + * tokens of the same type. Each token carries a serial number which is + * unique for that token, these tokens may have a different trade value + * for each individual token. The tokens are individually accounted and + * often carry additional unique properties. Tokens cannot be subdivided, + * and value is related to what the individual token represents. + *

+ * IWA taxonomy _non-fungible, whole, reference, unique_ */ NON_FUNGIBLE_UNIQUE = 1; } /** - * 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. + * A transaction sub type.
+ * This enumeration enables a set of transaction base fees to be broadly + * defined for a type of operation and also be modified, when necessary, + * based on specifics of the operation. * - * 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. + * ### Explanation + * The resource cost for a TokenMint operation is different between minting + * fungible/common and non-fungible/unique tokens. This `enum` is used to + * "mark" a cost as applying to one or the other.
+ * Similarly, the resource cost for a basic `tokenCreate` without a custom + * fee schedule may yield a _base_ fee of $1. The resource cost for a + * `tokenCreate` _with_ a custom fee schedule is different and may yield a + * _base_ fee of $2 or more. */ enum SubType { /** - * The resource prices have no special scope + * The resource cost for the transaction type has no additional attributes */ DEFAULT = 0; /** - * The resource prices are scoped to an operation on a fungible common token + * The resource cost for the transaction type includes 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 + * The resource cost for the transaction type includes 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 + * The resource cost for the transaction type includes 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 + * The resource cost for the transaction type includes an operation on a + * non-fungible/unique token with a custom fee schedule */ TOKEN_NON_FUNGIBLE_UNIQUE_WITH_CUSTOM_FEES = 4; /** - * The resource prices are scoped to a ScheduleCreate containing a ContractCall. + * The resource cost for the transaction type includes a ScheduleCreate + * containing a ContractCall. */ SCHEDULE_CREATE_CONTRACT_CALL = 5; + + /** + * The resource cost for the transaction type includes a TopicCreate + * with custom fees. + */ + TOPIC_CREATE_WITH_CUSTOM_FEES = 6; } /** * Possible Token Supply Types (IWA Compatibility). - * Indicates how many tokens can have during its lifetime. + * + * This `enum` indicates the limit of tokens that can exist during the + * lifetime of a token definition. The "infinite" supply is only theoretically + * infinite, as it is still limited to the magnitude of a 64-bit signed + * integer. A "finite" supply is further limited to a value specified when + * the token is created (or updated, if not immutable). */ enum TokenSupplyType { /** - * Indicates that tokens of that type have an upper bound of Long.MAX_VALUE. + * An unlimited supply.
+ * This indicates that tokens of this type have an upper bound of + * Long.MAX_VALUE.
+ * The supply is accounted in the smallest units of the token + * (i.e. 10-`decimals` whole tokens) */ INFINITE = 0; /** - * Indicates that tokens of that type have an upper bound of maxSupply, - * provided on token creation. + * A limited supply.
+ * This indicates that tokens of this type have an upper bound of + * `maxSupply`.
+ * The maximum supply SHALL be provided on token creation, but MAY be + * changed thereafter if the token has an `admin_key` set. */ FINITE = 1; } @@ -515,7 +768,8 @@ enum TokenSupplyType { */ enum TokenKeyValidation { /** - * Currently the default behaviour. It will perform all token key validations. + * Perform all token key validations.
+ * This is the default value and behavior. */ FULL_VALIDATION = 0; @@ -526,314 +780,417 @@ enum TokenKeyValidation { } /** - * Possible Freeze statuses returned on TokenGetInfoQuery or CryptoGetInfoResponse in - * TokenRelationship + * Possible token freeze status values. + * + * This is returned by `TokenGetInfoQuery` or `CryptoGetInfoResponse` + * in `TokenRelationship`. */ enum TokenFreezeStatus { /** - * UNDOCUMENTED + * The token does not support freeze or cannot be frozen for the designated + * account.
+ * Typically this indicates that the token does not have a `freeze_key` set. */ FreezeNotApplicable = 0; /** - * UNDOCUMENTED + * The token is currently frozen for the designated account. */ Frozen = 1; /** - * UNDOCUMENTED + * The token is not currently frozen for the designated account. */ Unfrozen = 2; } /** - * Possible KYC statuses returned on TokenGetInfoQuery or CryptoGetInfoResponse in TokenRelationship + * Possible token "KYC" status values. + * + * This is returned by `TokenGetInfoQuery` or `CryptoGetInfoResponse` + * in `TokenRelationship`. */ enum TokenKycStatus { /** - * UNDOCUMENTED + * The token does not support KYC or cannot grant KYC for the + * designated account.
+ * Typically this indicates that the token does not have a `kyc_key` set. */ KycNotApplicable = 0; /** - * UNDOCUMENTED + * The designated account is currently granted KYC status for the + * designated token. */ Granted = 1; /** - * UNDOCUMENTED + * The designated account is not currently granted KYC status for the + * designated token. */ Revoked = 2; } /** - * Possible Pause statuses returned on TokenGetInfoQuery + * Possible Pause status values. + * + * This is returned by `TokenGetInfoQuery` in `TokenRelationship`. */ enum TokenPauseStatus { /** - * Indicates that a Token has no pauseKey + * The token does not support pause or cannot be paused.
+ * Typically this indicates that the token does not have a `pause_key` set. */ PauseNotApplicable = 0; /** - * Indicates that a Token is Paused + * The token is currently paused. */ Paused = 1; /** - * Indicates that a Token is Unpaused. + * The token is not currently paused. */ Unpaused = 2; } /** - * A Key can be a public key from either the Ed25519 or ECDSA(secp256k1) signature schemes, where - * in the ECDSA(secp256k1) case we require the 33-byte compressed form of the public key. We call - * these public keys primitive keys. - * - * If an account has primitive key associated to it, then the corresponding private key must sign - * any transaction to transfer cryptocurrency out of it. - * - * A Key can also be the ID of a smart contract instance, which is then authorized to perform any - * precompiled contract action that requires this key to sign. - * - * Note that when a Key is a smart contract ID, it doesn't mean the contract with that ID - * will actually create a cryptographic signature. It only means that when the contract calls a - * precompiled contract, the resulting "child transaction" will be authorized to perform any action - * controlled by the 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 "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 primitive 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 has 3 levels: ThresholdKey -> KeyList -> Key. A KeyList which contains several primitive - * keys 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. + * A Key is an entity representing one or more cryptographic public/private key + * pairs and, optionally, the structure for how multiple signatures may be + * composed to meet complex multiple-signature authorization requirements. + * + * A Key can be a public key from either the Ed25519 or ECDSA(secp256k1) + * signature schemes. In the ECDSA(secp256k1) case we require the 33-byte + * compressed form of the public key. For simplicity, we call these + * cryptographic public keys `primitive` keys.
+ * If an entity has a primitive key associated to it, then the corresponding + * private key must sign any transaction to send tokens or perform other + * actions requiring authorization. + * + * A Key can also be the ID of a smart contract, which SHALL authorize that + * contract to execute any system contract with signing requirements that are + * met by the key.
+ * > Example + * >> If account `0.0.A` has a threshold key whose threshold is satisfied + * >> by a contract ID key for contract `0.0.C`, then when `0.0.C` is called, + * >> it is authorized to use system contracts to manage any asset owned by + * >> `0.0.A`. If the contract ID key is "delegatable", then `0.0.C` can even + * >> perform these actions when running code accessed via `DELEGATECALL`. + * + * A Key can be a "threshold key", which is a list of N keys, any M of which + * may sign in order for the signature to be considered valid. The value of + * M for a given threshold key MUST be less than or equal to N. A threshold + * key is sometimes called a "M-of-N" key. + * + * 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).
+ * This implies that the use of a key list is dependent on context. For + * example, an Hedera file that is created with a list of keys, SHALL require + * that all of those keys must sign a transaction to create or modify the file, + * but only one key from that list MUST sign a transaction to delete the file. + * So it is a single list that sometimes acts as a N-of-N threshold key, and + * sometimes acts as a 1-of-N threshold key.
+ * To reduce confusion this may cause, a key list SHALL always be considered + * N-of-N, unless specified otherwise in official documentation.
+ * A key list MAY have repeated primitive public keys, but the signature + * requirement for all keys in a repeated set SHALL be satisfied by a single + * valid signature. There is no mechanism to require a single key to sign a + * single transaction more than once. + * + * Any list or threshold key MAY have nested key lists or threshold keys. + * This allows, for example, the keys within a threshold signature to + * themselves be threshold, list, contract, or primitive keys. This nesting + * structure enables complex asymmetric multi-party signature requirements to + * be met. + * + * To ensure adequate performance and transaction security, key nesting is + * limited to at most fifteen(15) levels. */ message Key { oneof key { /** - * smart contract instance that is authorized as if it had signed with a key + * A smart contract instance that is authorized implicitly. + *

+ * This key type SHALL require that the code in the active message frame + * belong to the contract with the given id. */ ContractID contractID = 1; /** - * Ed25519 public key bytes + * An array of Ed25519 public key bytes. */ bytes ed25519 = 2; /** - * (NOT SUPPORTED) RSA-3072 public key bytes + * This option is not currently supported.
+ * An array of RSA-3072 public key bytes. */ - bytes RSA_3072 = 3; + bytes RSA_3072 = 3 [deprecated = true]; /** - * (NOT SUPPORTED) ECDSA with the p-384 curve public key bytes + * This option is not currently supported.
+ * An array of ECDSA, using the p-384 curve, public key bytes. */ - bytes ECDSA_384 = 4; + bytes ECDSA_384 = 4 [deprecated = true]; /** - * a threshold N followed by a list of M keys, any N of which are required to form a valid - * signature + * A threshold, M, combined with a list of N keys, any M of which are + * sufficient to form a valid signature. */ ThresholdKey thresholdKey = 5; /** - * A list of Keys of the Key type. + * A list of keys. This may be treated like a "N-of-N" threshold key, + * as a component of another key, or in some other manner as documented. */ KeyList keyList = 6; /** - * Compressed ECDSA(secp256k1) public key bytes + * A set of compressed ECDSA(secp256k1) public key bytes.
+ * This is an EVM compatibility format. */ bytes ECDSA_secp256k1 = 7; /** - * A smart contract that, if the recipient of the active message frame, should be treated - * as having signed. (Note this does not mean the code being executed in the frame - * will belong to the given contract, since it could be running another contract's code via - * delegatecall. So setting this key is a more permissive version of setting the - * contractID key, which also requires the code in the active message frame belong to the - * the contract with the given id.) + * A smart contract that, if the recipient of the active message frame, + * SHALL be imputed authorization.
+ * Setting this key type is a more permissive version of setting a + * contractID key. + *

+ * This key form SHALL NOT strictly require that the code being executed + * in the frame belong to the given contract. The code in frame MAY be + * running another contract via a `delegatecall`. */ ContractID delegatable_contract_id = 8; } } /** - * 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 threshold value and a list of public keys that, together, form a threshold + * signature requirement. Any subset of the keys in the list may satisfy the + * signature requirements of this type of key, provided the number of keys meets + * or exceeds the threshold. For example, if a particular key has a threshold of + * three(3) and eight(8) keys in the list, then any three(3) signatures, from + * the list of eight(8), is sufficient to authorize that key. + * + * For threshold purposes, all signatures from a single `primitive` key are + * considered a single signature, so that signature(s) from a single key SHALL + * NOT _directly_ meet a threshold greater than one(1). + * + * #### Note + * > It is possible to construct a complex key structure that _would_ enable a + * > single primitive key to successfully meet a threshold requirement. All + * > threshold keys SHOULD be carefully audited to ensure no one `primitive` + * > key, or smart contract, has disproportionate capability. */ message ThresholdKey { /** - * A valid signature set must have at least this many signatures + * A transaction MUST have valid signatures from at least this number of + * separate keys, from the `keys` list to be authorized by this key. */ uint32 threshold = 1; /** - * List of all the keys that can sign + * A list of the keys that MAY satisfy signature requirements of this key. */ 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.
+ * A `KeyList` requires all keys (N-of-N) to sign, unless otherwise + * specified in official documentation. A KeyList may contain repeated keys, + * but all such repeated keys are considered a single key when determining + * signature authorization. + * + * ### Additional Notes + * 1. An empty key list is the "standard" mechanism to represent an + * unassigned key. For example, if the `admin_key` of a token is set + * to the empty key list, then that token has no admin key, and + * functionality that requires an admin key to sign the + * transaction is disabled. */ message KeyList { /** - * list of keys + * A list of keys. All values in this list SHALL be non-null. + *

*/ repeated Key keys = 1; } /** - * This message is DEPRECATED and UNUSABLE with network nodes. It is retained - * here only for historical reasons. + * This message is deprecated and MUST NOT be used to communicate with + * network nodes. It is retained here only for historical reasons. + * + * Client software MUST NOT include this message in any request.
+ * Compliant nodes SHALL NOT accept any request containing this message. * - * Please use the SignaturePair and SignatureMap messages. + * Please use the `SignaturePair` and `SignatureMap` messages instead of + * this message. */ message Signature { option deprecated = true; oneof signature { /** - * smart contract virtual signature (always length zero) + * Smart contract virtual signature (always length zero). */ bytes contract = 1; /** - * ed25519 signature bytes + * Ed25519 signature bytes. */ bytes ed25519 = 2; /** - * RSA-3072 signature bytes + * RSA-3072 signature bytes. */ bytes RSA_3072 = 3; /** - * ECDSA p-384 signature bytes + * 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. + * 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. + * A list of M signatures, each corresponding to a Key in a KeyList + * of the same length. */ SignatureList signatureList = 6; } } /** - * This message is DEPRECATED and UNUSABLE with network nodes. It is retained - * here only for historical reasons. + * This message is deprecated and MUST NOT be used to communicate with network + * nodes. It is retained here only for historical reasons. * - * Please use the SignaturePair and SignatureMap messages. + * Client software MUST NOT include this message in any request.
+ * Compliant nodes SHALL NOT accept any request containing this message. + * + * Please use the `SignaturePair` and `SignatureMap` messages, in combination + * with `ThresholdKey` keys, instead of this message. */ message ThresholdSignature { option deprecated = true; /** - * 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; } /** - * This message is DEPRECATED and UNUSABLE with network nodes. It is retained - * here only for historical reasons. + * This message is deprecated and MUST NOT be used to communicate with network + * nodes. It is retained here only for historical reasons. + * + * Client software MUST NOT include this message in any request.
+ * Compliant nodes SHALL NOT accept any request containing this message. * - * Please use the SignaturePair and SignatureMap messages. + * Please use the `SignaturePair` and `SignatureMap` messages instead of + * this message. */ message SignatureList { option deprecated = true; /** - * 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 zero to the whole length of the public key for - * pubKeyPrefix. If zero bytes are used, then it must be that only one primitive key is required - * to sign the linked transaction; it will surely resolve to INVALID_SIGNATURE otherwise. - * - * IMPORTANT: In the special case that a signature is being provided for a key used to - * authorize a precompiled contract, the pubKeyPrefix must contain the entire public - * key! That is, if the key is a Ed25519 key, the pubKeyPrefix should be 32 bytes - * long. If the key is a ECDSA(secp256k1) key, the pubKeyPrefix should be 33 bytes long, - * since we require the compressed form of the public key. - * - * Only Ed25519 and ECDSA(secp256k1) keys and hence signatures are currently supported. + * A public key and signature pair.
+ * Only Ed25519 and ECDSA(secp256k1) keys and signatures are currently supported + * as cryptographic (non-implied) signatures. */ message SignaturePair { /** - * First few bytes of the public key + * Prefix bytes of the public key. + *

+ * The client may use any number of bytes from zero to the whole length of + * the public key for pubKeyPrefix. If zero bytes are used, then it MUST be + * true that only one cryptographic key is required to sign the associated + * transaction.
+ * If the `pubKeyPrefix` is 0 bytes and more than a single cryptographic + * key is required to sign the transaction, the request SHALL resolve to + * `INVALID_SIGNATURE`. + *

Important Note
+ * In the special case that a signature is provided to authorize a + * precompiled contract, the `pubKeyPrefix` MUST contain the _entire public + * key_.
+ * That is, if the key is an Ed25519 key, the `pubKeyPrefix` MUST be + * 32 bytes long and contain the full public key bytes.
+ * If the key is an ECDSA(secp256k1) key, the `pubKeyPrefix` MUST be + * 33 bytes long and contain the full _compressed_ form of the public key. + *
+ *

+ *

Purpose
+ *
The `pubKeyPrefix` exists to save cost. A signed transaction with + * shorter prefixes will have fewer bytes, and so will have a lower + * transaction fee. + * The prefixes, however, MUST be long enough to distinguish between all + * of the public keys that might be signing the transaction. Therefore, + * software signing a transaction SHOULD evaluate which keys might possibly + * be required to sign a transaction, and ensure that the shortest prefix + * that is sufficient to unambiguously identify the correct key is used. + *
*/ bytes pubKeyPrefix = 1; oneof signature { /** - * smart contract virtual signature (always length zero) + * A smart contract virtual signature. + *

+ * This value MUST be length zero, if set. */ bytes contract = 2; /** - * ed25519 signature + * An Ed25519 signature. */ bytes ed25519 = 3; /** - * RSA-3072 signature + * This option is not supported.
+ * A RSA-3072 signature. */ - bytes RSA_3072 = 4; + bytes RSA_3072 = 4 [deprecated = true]; /** - * ECDSA p-384 signature + * This option is not supported.
+ * ECDSA p-384 signature. */ - bytes ECDSA_384 = 5; + bytes ECDSA_384 = 5 [deprecated = true]; /** - * ECDSA(secp256k1) signature + * An ECDSA(secp256k1) signature. */ bytes ECDSA_secp256k1 = 6; } } /** - * 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 that + * signed a given transaction. + * + * If any public key matches more than one prefix in the signature map, + * the transaction containing that map SHALL fail immediately with the + * response code `KEY_PREFIX_MISMATCH`. */ message SignatureMap { /** - * Each signature pair corresponds to a unique Key required to sign the transaction. + * A list of signature pairs for a specific transaction.
+ * Each signature pair represents a single cryptographic (`primitive`) + * public key identified by a "prefix" value and the cryptographic + * signature produced for that key. */ repeated SignaturePair sigPair = 1; } @@ -842,373 +1199,418 @@ message SignatureMap { * The transactions and queries supported by Hedera Hashgraph. */ enum HederaFunctionality { + // FUTURE - Uncomment when https://github.com/hashgraph/pbj/issues/339 is fixed; + // currently the PBJ-generated unit tests fail when using reserved ordinals + // reserved 96, 97, 98, 99; + /** - * UNSPECIFIED - Need to keep first value as unspecified because first element is ignored and - * not parsed (0 is ignored by parser) + * Unused - The first value is unused because this default value is + * ambiguous with an "unset" value and therefore should not be used. */ NONE = 0; /** - * crypto transfer + * Transfer tokens among accounts. */ CryptoTransfer = 1; /** - * crypto update account + * Update an account. */ CryptoUpdate = 2; /** - * crypto delete account + * Delete an account. */ CryptoDelete = 3; /** - * Add a livehash to a crypto account + * Add a livehash to an account */ - CryptoAddLiveHash = 4; + CryptoAddLiveHash = 4 [deprecated = true]; /** - * Delete a livehash from a crypto account + * Delete a livehash from an account */ - CryptoDeleteLiveHash = 5; + CryptoDeleteLiveHash = 5 [deprecated = true]; /** - * Smart Contract Call + * Execute a smart contract call. */ ContractCall = 6; /** - * Smart Contract Create Contract + * Create a smart contract. */ ContractCreate = 7; /** - * Smart Contract update contract + * Update a smart contract. */ ContractUpdate = 8; /** - * File Operation create file + * Create a "file" stored in the ledger. */ FileCreate = 9; /** - * File Operation append file + * Append data to a "file" stored in the ledger. */ FileAppend = 10; /** - * File Operation update file + * Update a "file" stored in the ledger. */ FileUpdate = 11; /** - * File Operation delete file + * Delete a "file" stored in the ledger. */ FileDelete = 12; /** - * crypto get account balance + * Get the balance for an account. */ CryptoGetAccountBalance = 13; /** - * crypto get account record + * Get a full account record. */ CryptoGetAccountRecords = 14; /** - * Crypto get info + * Get information about a token. */ CryptoGetInfo = 15; /** - * Smart Contract Call + * Execute a local smart contract call.
+ * Used by contracts to call other contracts. */ ContractCallLocal = 16; /** - * Smart Contract get info + * Get information about a smart contract. */ ContractGetInfo = 17; /** - * Smart Contract, get the runtime code + * Get the compiled bytecode that implements a smart contract. */ ContractGetBytecode = 18; /** - * Smart Contract, get by solidity ID + * Get a smart contract record by reference to the solidity ID. */ GetBySolidityID = 19; /** - * Smart Contract, get by key + * Get a smart contract by reference to the contract key. */ GetByKey = 20; /** - * Get a live hash from a crypto account + * Get the live hash for an account */ - CryptoGetLiveHash = 21; + CryptoGetLiveHash = 21 [deprecated = true]; /** - * Crypto, get the stakers for the node + * Get the accounts proxy staking to a given account. */ - CryptoGetStakers = 22; + CryptoGetStakers = 22 [deprecated = true]; /** - * File Operations get file contents + * Get the contents of a "file" stored in the ledger. */ FileGetContents = 23; /** - * File Operations get the info of the file + * Get the metadata for a "file" stored in the ledger. */ FileGetInfo = 24; /** - * Crypto get the transaction records + * Get transaction record(s) for a specified transaction ID. */ TransactionGetRecord = 25; /** - * Contract get the transaction records + * Get all transaction records for a specified contract ID in + * the past 24 hours.
+ * deprecated since version 0.9.0 */ - ContractGetRecords = 26; + ContractGetRecords = 26 [deprecated = true]; /** - * crypto create account + * Create a new account */ CryptoCreate = 27; /** - * system delete file + * Delete a "system" "file" stored in the ledger.
+ * "System" files are files with special purpose and ID values within a + * specific range.
+ * These files require additional controls and can only be deleted when + * authorized by accounts with elevated privilege. */ SystemDelete = 28; /** - * system undelete file + * Undo the delete of a "system" "file" stored in the ledger.
+ * "System" files are files with special purpose and ID values within a + * specific range.
+ * These files require additional controls and can only be deleted when + * authorized by accounts with elevated privilege. This operation allows + * such files to be restored, within a reasonable timeframe, if + * deleted improperly. */ SystemUndelete = 29; /** - * delete contract + * Delete a smart contract */ ContractDelete = 30; /** - * freeze + * Stop all processing and "freeze" the entire network.
+ * This is generally sent immediately prior to upgrading the network.
+ * After processing this transactions all nodes enter a quiescent state. */ Freeze = 31; /** - * Create Tx Record + * Create a Transaction Record.
+ * This appears to be purely internal and unused. */ CreateTransactionRecord = 32; /** - * Crypto Auto Renew + * Auto-renew an account.
+ * This is used for internal fee calculations. */ CryptoAccountAutoRenew = 33; /** - * Contract Auto Renew + * Auto-renew a smart contract.
+ * This is used for internal fee calculations. */ ContractAutoRenew = 34; /** - * Get Version + * Get version information for the ledger.
+ * This returns a the version of the software currently running the network + * for both the protocol buffers and the network services (node). */ GetVersionInfo = 35; /** - * Transaction Get Receipt + * Get a receipt for a specified transaction ID. */ TransactionGetReceipt = 36; /** - * Create Topic + * Create a topic for the Hedera Consensus Service (HCS). */ ConsensusCreateTopic = 50; /** - * Update Topic + * Update an HCS topic. */ ConsensusUpdateTopic = 51; /** - * Delete Topic + * Delete an HCS topic. */ ConsensusDeleteTopic = 52; /** - * Get Topic information + * Get metadata (information) for an HCS topic. */ ConsensusGetTopicInfo = 53; /** - * Submit message to topic + * Publish a message to an HCS topic. */ ConsensusSubmitMessage = 54; + /** + * Submit a transaction, bypassing intake checking. + * Only enabled in local-mode. + */ UncheckedSubmit = 55; + /** - * Create Token + * Create a token for the Hedera Token Service (HTS). */ TokenCreate = 56; /** - * Get Token information + * Get metadata (information) for an HTS token. */ TokenGetInfo = 58; /** - * Freeze Account + * Freeze a specific account with respect to a specific HTS token. + *

+ * Once this transaction completes that account CANNOT send or receive + * the specified token. */ TokenFreezeAccount = 59; /** - * Unfreeze Account + * Remove a "freeze" from an account with respect to a specific HTS token. */ TokenUnfreezeAccount = 60; /** - * Grant KYC to Account + * Grant KYC status to an account for a specific HTS token. */ TokenGrantKycToAccount = 61; /** - * Revoke KYC from Account + * Revoke KYC status from an account for a specific HTS token. */ TokenRevokeKycFromAccount = 62; /** - * Delete Token + * Delete a specific HTS token. */ TokenDelete = 63; /** - * Update Token + * Update a specific HTS token. */ TokenUpdate = 64; /** - * Mint tokens to treasury + * Mint HTS token amounts to the treasury account for that token. */ TokenMint = 65; /** - * Burn tokens from treasury + * Burn HTS token amounts from the treasury account for that token. */ TokenBurn = 66; /** - * Wipe token amount from Account holder + * Wipe all amounts for a specific HTS token from a specified account. */ TokenAccountWipe = 67; /** - * Associate tokens to an account + * Associate a specific HTS token to an account. */ TokenAssociateToAccount = 68; /** - * Dissociate tokens from an account + * Dissociate a specific HTS token from an account. */ TokenDissociateFromAccount = 69; /** - * Create Scheduled Transaction + * Create a scheduled transaction */ ScheduleCreate = 70; /** - * Delete Scheduled Transaction + * Delete a scheduled transaction */ ScheduleDelete = 71; /** - * Sign Scheduled Transaction + * Sign a scheduled transaction */ ScheduleSign = 72; /** - * Get Scheduled Transaction Information + * Get metadata (information) for a scheduled transaction */ ScheduleGetInfo = 73; /** - * Get Token Account Nft Information + * Get NFT metadata (information) for a range of NFTs associated to a + * specific non-fungible/unique HTS token and owned by a specific account. */ - TokenGetAccountNftInfos = 74; + TokenGetAccountNftInfos = 74 [deprecated = true]; /** - * Get Token Nft Information + * Get metadata (information) for a specific NFT identified by token and + * serial number. */ - TokenGetNftInfo = 75; + TokenGetNftInfo = 75 [deprecated = true]; /** - * Get Token Nft List Information + * Get NFT metadata (information) for a range of NFTs associated to a + * specific non-fungible/unique HTS token. */ TokenGetNftInfos = 76; /** - * Update a token's custom fee schedule, if permissible + * Update a token's custom fee schedule. + *

+ * If a transaction of this type is not signed by the token + * `fee_schedule_key` it SHALL fail with INVALID_SIGNATURE, or + * TOKEN_HAS_NO_FEE_SCHEDULE_KEY if there is no `fee_schedule_key` set. */ TokenFeeScheduleUpdate = 77; /** - * Get execution time(s) by TransactionID, if available + * Get execution time(s) for one or more "recent" TransactionIDs. */ - NetworkGetExecutionTime = 78; + NetworkGetExecutionTime = 78 [deprecated = true]; /** - * Pause the Token + * Pause a specific HTS token */ TokenPause = 79; /** - * Unpause the Token + * Unpause a paused HTS token. */ TokenUnpause = 80; /** - * Approve allowance for a spender relative to the owner account + * Approve an allowance for a spender relative to the owner account, which + * MUST sign the transaction. */ CryptoApproveAllowance = 81; /** - * Deletes granted allowances on owner account + * Delete (unapprove) an allowance previously approved + * for the owner account. */ CryptoDeleteAllowance = 82; /** - * Gets all the information about an account, including balance and allowances. This does not get the list of - * account records. + * Get all the information about an account, including balance + * and allowances.
+ * This does not get a list of account records. */ GetAccountDetails = 83; /** - * Ethereum Transaction + * Perform an Ethereum (EVM) transaction.
+ * CallData may be inline if small, or in a "file" if large. */ EthereumTransaction = 84; /** - * Updates the staking info at the end of staking period to indicate new staking period has started. + * Used to indicate when the network has updated the staking information + * at the end of a staking period and to indicate a new staking period + * has started. */ NodeStakeUpdate = 85; /** - * Generates a pseudorandom number. + * Generate and return a pseudorandom number based on network state. */ UtilPrng = 86; /** - * Get a record for a transaction. + * Get a record for a "recent" transaction. */ - TransactionGetFastRecord = 87; + TransactionGetFastRecord = 87 [deprecated = true]; /** * Update the metadata of one or more NFT's of a specific token type. @@ -1231,7 +1633,8 @@ enum HederaFunctionality { NodeDelete = 91; /** - * Transfer one or more token balances held by the requesting account to the treasury for each token type. + * Transfer one or more token balances held by the requesting account + * to the treasury for each token type. */ TokenReject = 92; @@ -1241,7 +1644,8 @@ enum HederaFunctionality { TokenAirdrop = 93; /** - * Remove one or more pending airdrops from state on behalf of the sender(s) for each airdrop. + * Remove one or more pending airdrops from state on behalf of + * the sender(s) for each airdrop. */ TokenCancelAirdrop = 94; @@ -1251,170 +1655,242 @@ enum HederaFunctionality { TokenClaimAirdrop = 95; /** - * A message produced as part of Threshold Signature Scheme (TSS) processing. + * Submit a signature of a state root hash gossiped to other nodes */ - TssMessage = 96; + StateSignatureTransaction = 100; /** - * Submit a vote as part of the Threshold Signature Scheme (TSS) processing. + * Sign a particular history assembly. */ - TssVote = 97; + HistoryAssemblySignature = 104; /** - * Submit a node signature as part of the Threshold Signature Scheme (TSS) processing. + * Publish a roster history proof key to the network. */ - TssShareSignature = 98; + HistoryProofKeyPublication = 105; + + /** + * Vote for a particular history proof. + */ + HistoryProofVote = 106; } /** - * 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. + * A set of values the nodes use in determining transaction and query fees, and + * constants involved in fee calculations. + * + * Nodes SHALL multiply the amount of "resources" allocated to a transaction or + * query by the corresponding price to calculate the appropriate fee. Units are + * one-thousandth of a `tinyCent`. The "resource" allocations SHALL be estimated + * based on transaction characteristics and current network state, and MAY be + * further adjusted based on network load and congestion. + * + * This SHALL be used, in different contexts, for the cost _factors_ used to + * calculate charged amounts, for the resource accumulation, and for actual + * amounts to be charged.
+ * Amounts recorded here MUST be converted to tinybar according to the + * current active `ExchangeRate` for the network. */ message FeeComponents { /** - * A minimum, the calculated fee must be greater than this value + * Base: "minimum total fee". + *

+ * The calculated fee MUST be greater than this value. */ int64 min = 1; /** - * A maximum, the calculated fee must be less than this value + * Base: "maximum total fee". + *

+ * The calculated fee MUST be less than this value. */ int64 max = 2; /** - * A constant contribution to the fee + * Base: "constant fee".
+ * A baseline constant contribution to total fee. */ int64 constant = 3; /** - * The price of bandwidth consumed by a transaction, measured in bytes + * Bandwidth: "bytes per transaction".
+ * The fee for bandwidth consumed by a transaction, measured in bytes */ int64 bpt = 4; /** - * The price per signature verification for a transaction + * Signatures: "validations per transaction".
+ * The fee for signature verifications required by a transaction */ int64 vpt = 5; /** - * The price of RAM consumed by a transaction, measured in byte-hours + * Memory: "RAM byte-hours".
+ * The fee for RAM required to process a transaction, + * measured in byte-hours */ int64 rbh = 6; /** - * The price of storage consumed by a transaction, measured in byte-hours + * Disk: "storage byte-hours".
+ * The fee for storage required by a transaction, measured in byte-hours */ int64 sbh = 7; /** - * The price of computation for a smart contract transaction, measured in gas + * Compute: Ethereum term for a derivative EVM compute resource.
+ * The fee of computation for a smart contract transaction. The value of + * gas is set by a conversion rate, and is regularly updated to reflect + * reasonable and customary costs. */ int64 gas = 8; /** - * The price per hbar transferred for a transfer + * Ad valorem: "transferred value".
+ * The fee for HBAR transferred by a transaction. */ int64 tv = 9; /** - * The price of bandwidth for data retrieved from memory for a response, measured in bytes + * Response memory: "bytes per response".
+ * The fee for data retrieved from memory to deliver a response, + * measured in bytes */ int64 bpr = 10; /** - * The price of bandwidth for data retrieved from disk for a response, measured in bytes + * Response disk: "storage bytes per response".
+ * The fee for data retrieved from disk to deliver a response, + * measured in bytes */ int64 sbpr = 11; } /** - * The fees for a specific transaction or query based on the fee data. + * The fee schedule for a specific transaction or query based on the fee data. */ message TransactionFeeSchedule { /** - * A particular transaction or query + * An enumeration for a particular transaction or query.
+ * The functionality type determines the base cost parameters. */ HederaFunctionality hederaFunctionality = 1; /** - * Resource price coefficients + * Use `fees` instead of this field.
+ * Resource price coefficients. */ FeeData feeData = 2 [deprecated = true]; /** - * Resource price coefficients. Supports subtype price definition. + * The resource price coefficients for transaction type and any applicable + * subtypes.
+ * The multiple entries enable support for subtype price definitions. */ 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. + * A total fee, in component amounts charged for a transaction. + * + * Total fees are composed of three sets of components. + * - Node data, components that compensate the specific node that submitted + * the transaction. + * - Network data, components that compensate the Hedera network for gossiping + * the transaction and determining the consensus timestamp. + * - Service data, components that compensate the Hedera network for the ongoing + * maintenance and operation of the network, as well as ongoing development + * of network services. + * + * Fee components are recorded in thousandths of a tiny cent, and the network + * exchange rate converts these to tinybar amounts, which are what the network + * charges for transactions and what the network reports in the record stream. */ message FeeData { /** - * Fee paid to the submitting node + * Fee components to be paid to the submitting node. */ FeeComponents nodedata = 1; /** - * Fee paid to the network for processing a transaction into consensus + * Fee components to be paid to the network for bringing a + * transaction to consensus. */ FeeComponents networkdata = 2; /** - * Fee paid to the network for providing the service associated with the - * transaction; for instance, storing a file + * Fee components to be paid to the network for providing the immediate and + * ongoing services associated with executing the transaction, maintaining + * the network, and developing the network software. */ FeeComponents servicedata = 3; /** - * SubType distinguishing between different types of FeeData, correlating - * to the same HederaFunctionality + * A sub-type distinguishing between different types of `FeeData` that may + * apply to the same base transaction type (associated with + * an `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. + * A set of fee schedules covering all transaction types and query types, along + * with a specific time at which this fee schedule will expire. + * + * Nodes SHALL use the most recent unexpired fee schedule to determine the fees + * for all transactions based on various resource components imputed to each + * transaction. */ message FeeSchedule { /** - * List of price coefficients for network resources + * Sets of fee coefficients for various transaction or query types. */ repeated TransactionFeeSchedule transactionFeeSchedule = 1; /** - * FeeSchedule expiry time + * A time, in seconds since the `epoch`, when this fee schedule + * will expire. + *

+ * For this purpose, `epoch` SHALL be the UNIX epoch + * with 0 at `1970-01-01T00:00:00.000Z`. */ TimestampSeconds expiryTime = 2; } /** - * This contains two Fee Schedules with expiry timestamp. + * The "current" fee schedule and the "next" fee schedule. + * + * The current fee schedule is the schedule that SHALL apply to the current + * transaction.
+ * The next fee schedule is the schedule that SHALL apply after the current + * schedule expires.
+ * We store both to avoid a condition where transactions are processed very + * near the time when a fee schedule expires and it might be indeterminate + * which fees to apply. With both current and next fee schedule the network + * can deterministically apply the correct fee schedule based on consensus + * timestamp for each transaction. */ message CurrentAndNextFeeSchedule { /** - * Contains current Fee Schedule + * A current, unexpired, fee schedule. */ FeeSchedule currentFeeSchedule = 1; /** - * Contains next Fee Schedule + * A future fee schedule to use when the current schedule expires. */ 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. + * A network node endpoint.
+ * Each network node in the global address book publishes one or more endpoints + * which enable the nodes to communicate both with other nodes, for gossip, and + * with clients to receive transaction requests. + * + * This message supports IPv4 with address and TCP port, + * and MAY include a FQDN instead of an IP address.
+ * IPv6 is not currently supported. * * When the `domain_name` field is set, the `ipAddressV4` field * MUST NOT be set.
@@ -1423,301 +1899,449 @@ message CurrentAndNextFeeSchedule { */ message ServiceEndpoint { /** - * The 4-byte IPv4 address of the endpoint encoded in left to right order - * (e.g. 127.0.0.1 has bytes [127, 0, 0, 1]) + * A 32-bit IPv4 address.
+ * This is the address of the endpoint, encoded in pure "big-endian" + * (i.e. left to right) order (e.g. `127.0.0.1` has hex bytes in the + * order `7F`, `00`, `00`, `01`). */ bytes ipAddressV4 = 1; /** - * The port of the service endpoint + * A TCP port to use. + *

+ * This value MUST be between 0 and 65535, inclusive. */ int32 port = 2; /** - * A node domain name.
- * This MUST be the fully qualified domain(DNS) name of the node.
- * This value MUST NOT be more than 253 characters. - * domain_name and ipAddressV4 are mutually exclusive. - * When the `domain_name` field is set, the `ipAddressV4` field MUST NOT be set.
- * When the `ipAddressV4` field is set, the `domain_name` field MUST NOT be set. + * A node domain name. + *

+ * This MUST be the fully qualified domain name of the node.
+ * This value MUST NOT exceed 253 characters.
+ * When the `domain_name` field is set, the `ipAddressV4` + * field MUST NOT be set.
+ * When the `ipAddressV4` field is set, the `domain_name` + * field MUST NOT be set. */ string domain_name = 3; } /** - * 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.) + * 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 active fields are populated in the `0.0.102` address book file.
+ * Only fields documented with "`0.0.101` field" are populated in the 0.0.101 + * address book file. * - * 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. + * This message MAY be superseded by messages in state/addressbook/node.proto + * and node_get_info.proto. */ 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 + * ServiceEndpoint is now used to retrieve a node's list of IP + * addresses and ports.
+ * The IP address of the Node, as a string, encoded in UTF-8.
+ * This value SHALL NOT be populated. */ 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 + * ServiceEndpoint is now used to retrieve a node's list of IP + * addresses and ports.
+ * The port number of the grpc server for the node.
+ * This value SHALL NOT be populated. */ int32 portno = 2 [deprecated = true]; /** - * Usage is deprecated, nodeAccountId is preferred to retrieve a node's account ID + * Description provides short text functionality.
+ * A short description of the node. + *

+ * This field SHALL NOT be populated. */ bytes memo = 3 [deprecated = true]; /** - * The node's X509 RSA public key used to sign stream files (e.g., record stream - * files). Precisely, this field is a string of hexadecimal characters which, - * translated to binary, are the public key's DER encoding. + * A hexadecimal String encoding of an X509 public key. + *

+ * This X509 RSA _public_ key SHALL be used to verify record stream files + * (e.g., record stream files).
+ * This field SHALL be a string of hexadecimal characters, encoded UTF-8, + * which, translated to binary, form the public key DER encoding. */ string RSA_PubKey = 4; /** - * # A non-sequential identifier for the node + * A numeric identifier for the node. + *

+ * This value SHALL NOT be sequential. + *

+ * A `0.0.101` field */ int64 nodeId = 5; /** - * # The account to be paid for queries and transactions sent to this node + * An account to be paid the "node" portion of transaction fees.
+ * The "node" fees are paid to the node that submitted the transaction. + *

+ * A `0.0.101` field */ AccountID nodeAccountId = 6; /** - * # Hash of the node's TLS certificate. Precisely, this field is a string of - * hexadecimal characters which, translated to binary, are the SHA-384 hash of - * the UTF-8 NFKD encoding of the node's TLS cert in PEM format. Its value can be - * used to verify the node's certificate it presents during TLS negotiations. + * A hash of the node's TLS certificate. + *

+ * This field SHALL be a string of hexadecimal characters, encoded UTF-8, + * which, translated to binary, form a SHA-384 hash of the node's TLS + * certificate in PEM format. + * This TLS certificate MUST be encoded UTF-8 and normalized according to + * the NFKD form prior to computing the hash value.
+ * The value of this field SHALL be used to verify the node TLS + * certificate when presented during protocol negotiation. + *

+ * A `0.0.101` field */ bytes nodeCertHash = 7; /** - * # A node's service IP addresses and ports + * A node's service IP addresses and TCP ports.
+ * Nodes require multiple endpoints to ensure that inter-node communication + * (e.g. gossip) is properly separated from client communication to + * API endpoints. + *

+ * A `0.0.101` field */ repeated ServiceEndpoint serviceEndpoint = 8; /** - * A description of the node, with UTF-8 encoding up to 100 bytes + * A short description of the node. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string description = 9; /** - * [Deprecated] The amount of tinybars staked to the node + * This is replaced by per-account stake tracking and dynamic + * calculation.
+ * The amount of tinybar staked to the node.
+ * This value SHOULD NOT be populated, and SHALL be ignored. */ int64 stake = 10 [deprecated = true]; } /** - * 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. + * A list of nodes and their metadata that contains details of the nodes + * running 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 + * Published data for 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. + * A software version according to "[semantic versioning](https://semver.org/)" + * or "date versioning". + * + * Hedera currently modifies the "typical" semantic versioning somewhat, the + * `major` version is always `0`, and each release increments the `minor` + * version. The `patch` and `pre` components are used in the typical manner. + * The `build` component is not generally used. */ message SemanticVersion { /** - * Increases with incompatible API changes + * A major version.
+ * Hedera does not increment this value and retains a `0` value to + * indicate that API may change for any release. + *

+ * This value SHALL increment for an incompatible API change.
*/ int32 major = 1; /** - * Increases with backwards-compatible new functionality + * A minor version.
+ * Hedera increments this value with each release.
+ * There may be incompatible API changes in any Hedera Services release. + *

+ * This value SHALL increment for backwards-compatible new + * functionality. */ int32 minor = 2; /** - * Increases with backwards-compatible bug fixes + * A patch version. + *

+ * This value SHALL increment for 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' + * A pre-release version. + *

+ * This MAY be denoted by appending a hyphen and a series of dot separated + * identifiers per [Semver Specification](https://semver.org/#spec-item-9); + * given a string `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 + * A build version. + *

+ * Build version MAY be denoted by appending a plus sign and a series of + * dot separated identifiers immediately following the patch or pre-release + * version per [Semver Specification](https://semver.org/#spec-item-10); so + * given a string `0.14.0-alpha.1+21AF26D3`, this field * would contain '21AF26D3' */ string build = 5; } /** - * UNDOCUMENTED + * A single runtime configuration setting. + * + * Typically a name-value pair, this may also contain a small amount of + * associated data. */ message Setting { /** - * name of the property + * A name for this setting property. */ string name = 1; /** - * value of the property + * A value for this setting property. */ string value = 2; /** - * any data associated with property + * A small quantity of data associated with this setting. + *

+ * This SHOULD be less than 100 bytes.
+ * If the value is a string, it MUST be encoded UTF-8. */ bytes data = 3; } /** - * UNDOCUMENTED + * Setting values representing a source of runtime configuration information. */ message ServicesConfigurationList { /** - * list of name value pairs of the application properties + * A List of `Setting` values, typically read from application properties. */ repeated Setting nameValue = 1; } /** - * Token's information related to the given Account + * An Hedera Token Service token relationship. A token relationship describes + * the connection between an Account and a Token type, including the current + * account balance in that token. + * + * A `TokenRelationship` SHALL contain, for the designated token and enclosing + * account, The account's current balance, whether the account has KYC granted, + * whether the assets are frozen and whether the association was automatic.
+ * A `TokenRelationship` MAY also contain the `symbol` and `decimals` values + * copied from the token.
+ * `TokenRelationship` entries SHALL be valid only within the context of a + * `GetAccountDetails` query response, or other enclosing message, which + * specifies the account side of the relationship. */ message TokenRelationship { /** - * The ID of the token + * A token identifier. + *

+ * This MUST match an existing token that is not deleted. */ TokenID tokenId = 1; /** - * The Symbol of the token + * A token symbol. + *

+ * This MUST match an existing token that is not deleted.
+ * This MUST match the value for the token identified in `tokenId`. */ 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 + * An account balance for this token. + *

+ * For fungible/common tokens this SHALL be the balance that the + * account holds of that token. The value is provided as an integer amount + * of the smallest unit of the token (i.e. 10`-decimals` whole + * tokens).
+ * For non-fungible/unique tokens this SHALL be the whole number of + * unique tokens held by the account for this token type. */ uint64 balance = 3; /** - * The KYC status of the account (KycNotApplicable, Granted or Revoked). If the token does not - * have KYC key, KycNotApplicable is returned + * A KYC status for the account with respect to this token. + *

+ * This may be `KycNotApplicable`, `Granted` or `Revoked` and, if KYC is + * not supported for this token (e.g. the `kyc_key` of the token is not + * set), this SHALL be `KycNotApplicable`. */ TokenKycStatus kycStatus = 4; /** - * The Freeze status of the account (FreezeNotApplicable, Frozen or Unfrozen). If the token does - * not have Freeze key, FreezeNotApplicable is returned + * A Freeze status for the account with respect to this token. + *

+ * This value SHALL be one of `FreezeNotApplicable`, `Frozen` + * or `Unfrozen`.
+ * If the token cannot freeze account assets (e.g. the `freeze_key` of the + * token is not set), this SHALL be `FreezeNotApplicable`. */ TokenFreezeStatus freezeStatus = 5; /** - * Tokens divide into 10decimals pieces + * A maximum "precision" for this token. + *

+ * This value MUST match the `decimals` field of the token identified in + * the `tokenId` field.
+ * A single whole token SHALL be divided into at most + * 10`decimals` sub-units. */ uint32 decimals = 6; /** - * Specifies if the relationship is created implicitly. False : explicitly associated, True : - * implicitly associated. + * An automatic association flag. + *

+ * This SHALL be set if the relationship was created implicitly + * (automatically).
+ * This SHALL be unset if the relationship was created explicitly + * (manually) via a `TokenAssociate` transaction. */ bool automatic_association = 7; } /** - * A number of transferable units of a certain token. + * A number of _transferable units_ of a specified 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). + * The transferable unit of a token is its smallest denomination, as given by + * the token's `decimals` property. Each minted token contains + * 10`decimals` 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 { /** - * A unique token id + * A token identifier. */ 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 + * A number of transferable units of the identified token. + *

+ * For fungible/common tokens this SHALL be the balance, in units of + * 10`-decimals` whole tokens.
+ * For non-fungible/unique tokens, this SHALL be the number of + * individual unique tokens in this balance. */ uint64 balance = 2; /** - * Tokens divide into 10decimals pieces + * A number of "decimals" precision. + *

+ * This MUST match the `decimals` value for the token identified by the + * `tokenId` field. */ uint32 decimals = 3; } /** - * A sequence of token balances + * A set of token balance values. + * + * Each entry describes the balance the enclosing account holds for a specific + * token. The balance is an amount for a fungible/common token or a count for + * a non-fungible/unique token. */ message TokenBalances { + /** + * A list of token balance values.
+ * Each entry represents a single account balance for a single token. + */ repeated TokenBalance tokenBalances = 1; } -/* A token - account association */ +/** + * An association between a token and an account. + * + * An account must be associated with a token before that account can transact + * in (send or receive) that token. + */ message TokenAssociation { - TokenID token_id = 1; // The token involved in the association - AccountID account_id = 2; // The account involved in the association + /** + * A token identifier for the associated token. + */ + TokenID token_id = 1; + + /** + * An account identifier for the associated account. + */ + AccountID account_id = 2; } /** - * Staking metadata for an account or a contract returned in CryptoGetInfo or ContractGetInfo queries + * Staking information for an account or a contract. + * + * This is used for responses returned from `CryptoGetInfo` or + * `ContractGetInfo` queries. */ message StakingInfo { /** - * If true, this account or contract declined to receive a staking reward. + * A flag indicating that the holder of this account has chosen to decline + * staking rewards. */ bool decline_reward = 1; /** - * The staking period during which either the staking settings for this account or contract changed (such as starting - * staking or changing staked_node_id) or the most recent reward was earned, whichever is later. If this account or contract - * is not currently staked to a node, then this field is not set. + * A `Timestamp` of the start time for the latest active staking period. + *

+ * This MUST be a period during which either the staking settings for this + * account or contract changed or the account or contract received staking + * rewards, whichever is later. Examples of a change in staking settings + * include starting staking or changing the staked_node_id.
+ * If this account or contract is not currently staked to a node, then this + * field SHALL NOT be set. */ Timestamp stake_period_start = 2; /** - * The amount in tinybars that will be received in the next reward situation. + * An amount, in tinybar, to be received in the next reward payout.
+ * Rewards are not paid out immediately; for efficiency reasons rewards are + * only paid out as part of another transaction involving that account. */ int64 pending_reward = 3; /** - * The total of balance of all accounts staked to this account or contract. + * A proxy-staked balance.
+ * The total HBAR balance of all accounts that delegate staking to this + * account or contract. */ int64 staked_to_me = 4; - /** - * ID of the account or node to which this account or contract is staking. - */ oneof staked_id { - /** - * The account to which this account or contract is staking. + * A delegated stake. + *

+ * This account delegates to the indicated account for staking purposes. */ AccountID staked_account_id = 5; /** - * The ID of the node this account or contract is staked to. + * A direct stake. + *

+ * This accounts stakes its balance to the designated node. */ int64 staked_node_id = 6; } @@ -1726,20 +2350,25 @@ message StakingInfo { /** * A unique, composite, identifier for a pending airdrop. * - * Each pending airdrop SHALL be uniquely identified by a PendingAirdropId. - * A PendingAirdropId SHALL be recorded when created and MUST be provided in any transaction - * that would modify that pending airdrop (such as a `claimAirdrop` or `cancelAirdrop`). + * Each pending airdrop SHALL be uniquely identified by + * a `PendingAirdropId`.
+ * A `PendingAirdropId` SHALL be recorded when created and MUST be provided in + * any transaction that would modify that pending airdrop + * (such as a `claimAirdrop` or `cancelAirdrop`). */ message PendingAirdropId { /** - * A sending account.
- * This is the account that initiated, and SHALL fund, this pending airdrop.
+ * A sending account. + *

+ * This is the account that initiated, and SHALL fund, + * this pending airdrop.
* This field is REQUIRED. */ AccountID sender_id = 1; /** - * A receiving account.
+ * A receiving account. + *

* This is the ID of the account that SHALL receive the airdrop.
* This field is REQUIRED. */ @@ -1747,18 +2376,21 @@ message PendingAirdropId { oneof token_reference { /** - * A token ID.
- * This is the type of token for a fungible/common token airdrop.
- * This field is REQUIRED for a fungible/common token and MUST NOT be used for a - * non-fungible/unique token. + * A token identifier.
+ * This is the type of token for a fungible/common token airdrop. + *

+ * This field is REQUIRED for a fungible/common token and MUST NOT + * be used for a non-fungible/unique token. */ TokenID fungible_token_type = 3; /** - * The id of a single NFT, consisting of a Token ID and serial number.
- * This is the type of token for a non-fungible/unique token airdrop.
- * This field is REQUIRED for a non-fungible/unique token and MUST NOT be used for a - * fungible/common token. + * The id of a single NFT
+ * This is the type of token for a non-fungible/unique token airdrop + * and consists of a Token ID and serial number. + *

+ * This field is REQUIRED for a non-fungible/unique token and + * MUST NOT be used for a fungible/common token. */ NftID non_fungible_token = 4; } @@ -1767,24 +2399,28 @@ message PendingAirdropId { /** * A single pending airdrop value. * - * This message SHALL record the airdrop amount for a fungible/common token.
+ * This message SHALL record the airdrop amount for a + * fungible/common token.
* This message SHOULD be null for a non-fungible/unique token.
- * If a non-null `PendingAirdropValue` is set for a non-fungible/unique token, the amount - * field MUST be `0`. + * If a non-null `PendingAirdropValue` is set for a non-fungible/unique + * token, the amount field MUST be `0`. * - * It is RECOMMENDED that implementations store pending airdrop information as a key-value map - * from `PendingAirdropId` to `PendingAirdropValue`, with a `null` value used for non-fungible - * pending airdrops. + * It is RECOMMENDED that implementations store pending airdrop information + * as a key-value map from `PendingAirdropId` to `PendingAirdropValue`, with + * a `null` value used for non-fungible pending airdrops. */ message PendingAirdropValue { /** * An amount to transfer for fungible/common tokens.
* This is expressed in the smallest available units for that token - * (i.e. 10-`decimals` whole tokens).
- * This amount SHALL be transferred from the sender to the receiver, if claimed.
- * If the token is a fungible/common token, this value MUST be strictly greater than `0`. - * If the token is a non-fungible/unique token, this message SHOULD NOT be set, and if - * set, this field MUST be `0`. + * (i.e. 10-`decimals` whole tokens). + *

+ * This amount SHALL be transferred from the sender to the receiver, + * if claimed.
+ * If the token is a fungible/common token, this value MUST be strictly + * greater than `0`.
+ * If the token is a non-fungible/unique token, this message SHOULD NOT + * be set, and if set, this field MUST be `0`. */ uint64 amount = 1; } diff --git a/sdk/src/main/proto/block_info.proto b/sdk/src/main/proto/block_info.proto index cdd0508d6..f18c5d08b 100644 --- a/sdk/src/main/proto/block_info.proto +++ b/sdk/src/main/proto/block_info.proto @@ -1,13 +1,21 @@ +/** + * # Block Info + * Information about the most recent block; including block hashes, current and + * previous start times, etc... + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ import "timestamp.proto"; @@ -29,39 +36,76 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** - * Information about ongoing, most recently completed, and last 256 blocks. + * Information for a transaction block. + * + * This includes: + * - last block number. + * - consensus times for: + * - previous block start. + * - current block start. + * - last handled transaction. + * - hash data for a rolling window of 256 blocks. + * - whether migration records were produced. */ message BlockInfo { - /** - * The last block number, this is the last completed immutable block. - */ - int64 last_block_number = 1; - /** - * The consensus time of the first transaction of the last block, this is the last completed immutable block. - */ - Timestamp first_cons_time_of_last_block = 2; - /** - * SHA384 48 byte hashes of the last 256 blocks in single byte array. - * First 48 bytes is the oldest block. - * Last 48 bytes is the newest block, which is the last fully completed immutable block. - * If we are shortly after genesis and there are less than 256 blocks then this could contain less than 256 hashes. - */ - bytes block_hashes = 3; - /** - * The consensus time of the last transaction that was handled by the node. This property is how we 'advance the - * consensus clock', i.e. continually setting this property to the latest consensus timestamp (and thus transaction) - * handled by the node. - */ - Timestamp cons_time_of_last_handled_txn = 4; - /** - * A flag indicating whether migration records have been published. This property should be marked 'false' - * immediately following a node upgrade, and marked 'true' once the migration records (if any) are published, which - * should happen during the first transaction handled by the node. - */ - bool migration_records_streamed = 5; - /** - * The consensus time of the first transaction in the current block; necessary for reconnecting nodes to detect - * when the current block is finished. - */ - Timestamp first_cons_time_of_current_block = 6; + + /** + * A block number. + *

+ * The block number of the last completed immutable block. + */ + int64 last_block_number = 1; + + /** + * A consensus timestamp. + *

+ * The consensus time of the first transaction for the last completed immutable block. + */ + Timestamp first_cons_time_of_last_block = 2; + + /** + * A list of the last 256 block hashes.
+ * This is the SHA384 48 byte hashes of the previous 256 blocks, + * collected in a single byte array. + *

+ * The first 48 bytes SHALL be the oldest block in the list.
+ * The last 48 bytes SHALL be the newest block, which is the last fully + * completed immutable block.
+ * This SHALL contain less than 256 block hashes if there are less than 256 + * preceding blocks; for instance, shortly after network genesis the network + * will not have processed 256 blocks yet. + *

+ * This MAY change significantly for Block Stream (HIP TBD). + */ + bytes block_hashes = 3; + + /** + * A consensus timestamp. + *

+ * The consensus time of the last transaction that was handled by the node + * within the current block.
+ * This property is how we 'advance the consensus clock'. The node MUST + * continually set this property to the consensus timestamp for the most + * recent transaction completed by the node. + */ + Timestamp cons_time_of_last_handled_txn = 4; + + /** + * A flag indicating that migration records have been published. + *

+ * This property SHALL be `false` immediately following a node upgrade
+ * This SHALL be set 'true' as migration records, if any, are published. + * Migration records are typically published "during" the first transaction + * handled by the node following startup. + */ + bool migration_records_streamed = 5; + + /** + * A consensus timestamp. + *

+ * The consensus time of the first transaction in the current block; + * necessary for reconnecting nodes to detect when the current block + * is finished. + */ + Timestamp first_cons_time_of_current_block = 6; } diff --git a/sdk/src/main/proto/block_stream_info.proto b/sdk/src/main/proto/block_stream_info.proto index 06608de91..cf3f36809 100644 --- a/sdk/src/main/proto/block_stream_info.proto +++ b/sdk/src/main/proto/block_stream_info.proto @@ -12,7 +12,7 @@ */ syntax = "proto3"; -package com.hedera.hashgraph.hapi.node.state.blockstream; +package com.hedera.hapi.node.state.blockstream; /* * Copyright (C) 2024 Hedera Hashgraph, LLC diff --git a/sdk/src/main/proto/bytecode.proto b/sdk/src/main/proto/bytecode.proto index 8652fce94..b441161a3 100644 --- a/sdk/src/main/proto/bytecode.proto +++ b/sdk/src/main/proto/bytecode.proto @@ -1,13 +1,20 @@ +/** + * # EVM Bytecode + * The verified bytecode of an EVM contract for the Hedera Smart Contract service. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +26,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,7 +33,10 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** - * The bytecode for a contract id. + * The bytecode for a contract account. + * + * This is not referred to by any other protocol buffer, but is used internally + * within the Hedera Node software. */ message Bytecode { /** diff --git a/sdk/src/main/proto/common.proto b/sdk/src/main/proto/common.proto index 5eb76044a..517458f29 100644 --- a/sdk/src/main/proto/common.proto +++ b/sdk/src/main/proto/common.proto @@ -1,14 +1,27 @@ +/** + * # State Common + * Two older messages used in rare cases. + * - EntityNumber is used to store The last used entity number in state, so + * that all entities in state have unique entity numbers, even across types. + * - EntityIDPair is used to store a Token/Account pair in certain rare cases. + * + * Where possible, these messages SHOULD NOT be used. A primitive `int64` or + * `google.protobuf.Int64Value` wrapper is preferred instead of `EntityNumber + * and `TokenAssociation` is preferred instead of `EntityIDPair`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; -import "basic_types.proto"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -20,24 +33,46 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; +import "basic_types.proto"; + /** * A single 64-bit number identifying a Hedera native entity. + * + * Deprecated.
+ * A primitive `int64` or `google.protobuf.Int64Value` wrapper is preferred. */ message EntityNumber { + option deprecated = true; + + /** + * The entity number to store. + */ int64 number = 1; } /** - * Pair of AccountID and TokenID to represent TokenRelation + * A Pair of AccountID and TokenID.
+ * This is used as a key in certain cases. + * + * Deprecated.
+ * The TokenAssociation message should be used instead of this message. */ message EntityIDPair { - AccountID account_id = 1; - TokenID token_id = 2; + option deprecated = true; + + /** + * An account identifier for the associated account. + */ + AccountID account_id = 1; + + /** + * A token identifier for the associated token. + */ + TokenID token_id = 2; } diff --git a/sdk/src/main/proto/congestion_level_starts.proto b/sdk/src/main/proto/congestion_level_starts.proto index d9a3ac25a..4157cdcce 100644 --- a/sdk/src/main/proto/congestion_level_starts.proto +++ b/sdk/src/main/proto/congestion_level_starts.proto @@ -1,13 +1,21 @@ +/** + * # Congestion timestamps + * The timestamp values indicating when congestion pricing changed. + * + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ import "timestamp.proto"; @@ -28,14 +35,28 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; +/** + * Two lists of congestion pricing level "start" times. Each list details the + * start of each time period when the congestion pricing level changed + * (increasing, or decreasing, the congestion fee multiplier). + * + */ message CongestionLevelStarts { - /** - * Timestamps defining generic congestion levels. - */ - repeated Timestamp generic_level_starts = 1; + /** + * Timestamps for each point where "entity utilization" congestion pricing + * levels changed. + *

+ * If congestion pricing has not occurred then this SHALL contain a single + * timestamp of value 0. + */ + repeated Timestamp generic_level_starts = 1; - /** - * Timestamps defining gas congestion levels. - */ - repeated Timestamp gas_level_starts = 2; + /** + * Timestamps for each point where "gas utilization" congestion pricing + * levels changed. + *

+ * If congestion pricing has not occurred then this SHALL contain a single + * timestamp of value 0. + */ + repeated Timestamp gas_level_starts = 2; } diff --git a/sdk/src/main/proto/consensus_create_topic.proto b/sdk/src/main/proto/consensus_create_topic.proto index cd2e46877..5b578e2d0 100644 --- a/sdk/src/main/proto/consensus_create_topic.proto +++ b/sdk/src/main/proto/consensus_create_topic.proto @@ -1,13 +1,21 @@ +/** + * # Create Topic + * Create a new topic for the Hedera Consensus Service (HCS). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,47 +34,150 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; import "basic_types.proto"; +import "custom_fees.proto"; import "duration.proto"; /** - * See [ConsensusService.createTopic()](#proto.ConsensusService) + * Create a topic to accept and group consensus messages. + * + * If `autoRenewAccount` is specified, that account Key MUST also sign this + * transaction.
+ * If `adminKey` is set, that Key MUST sign the transaction.
+ * On success, the resulting `TransactionReceipt` SHALL contain the newly + * created `TopicId`. + * + * The `autoRenewPeriod` on a topic MUST be set to a value between + * `autoRenewPeriod.minDuration` and `autoRenewPeriod.maxDuration`. These + * values are configurable, typically 30 and 92 days.
+ * This also sets the initial expirationTime of the topic. + * + * If no `adminKey` is set on a topic + * -`autoRenewAccount` SHALL NOT be set on the topic. + * - A `deleteTopic` transaction SHALL fail. + * - An `updateTopic` transaction that only extends the expirationTime MAY + * succeed. + * - Any other `updateTopic` transaction SHALL fail. + * + * If the topic expires and is not automatically renewed, the topic SHALL enter + * the `EXPIRED` state. + * - All transactions on the topic SHALL fail with TOPIC_EXPIRED + * - Except an updateTopic() call that only extends the expirationTime. + * - getTopicInfo() SHALL succeed, and show the topic is expired. + * The topic SHALL remain in the `EXPIRED` state for a time determined by the + * `autorenew.gracePeriod` (configurable, originally 7 days).
+ * After the grace period, if the topic's expirationTime is not extended, the + * topic SHALL be automatically deleted from state entirely, and cannot be + * recovered or recreated. + * + * ### Block Stream Effects + * None */ message ConsensusCreateTopicTransactionBody { /** - * Short publicly visible memo about the topic. No guarantee of uniqueness. + * A short memo for this topic. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ 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 modification of the topic after it is created. + *

+ * If this field is set, that key MUST sign this transaction.
+ * If this field is set, that key MUST sign each future transaction to + * update or delete the topic.
+ * An updateTopic transaction that _only_ extends the topic expirationTime + * (a "manual renewal" transaction) SHALL NOT require admin key + * signature.
+ * A topic without an admin key SHALL be immutable, except for expiration + * and renewal.
+ * If adminKey is not set, then `autoRenewAccount` SHALL NOT be set. */ Key adminKey = 2; /** - * Access control for submitMessage. - * If unspecified, no access control is performed on ConsensusService.submitMessage (all submissions are allowed). + * Access control for message submission to the topic. + *

+ * If this field is set, that key MUST sign each consensus submit message + * for this topic.
+ * If this field is not set then any account may submit a message on the + * topic, without restriction. */ 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, in seconds, for the topic.
+ * This is also the number of seconds for which the topic SHALL be + * automatically renewed upon expiring, if it has a valid auto-renew + * account. + *

+ * This value MUST be set.
+ * This value MUST be greater than the configured + * MIN_AUTORENEW_PERIOD.
+ * This value MUST be less than the configured MAX_AUTORENEW_PERIOD. */ 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. + * The ID of the account to be charged renewal fees at the topic's + * expirationTime to extend the lifetime of the topic. + *

+ * The topic lifetime SHALL be extended by the smallest of the following: + *

    + *
  • The current `autoRenewPeriod` duration.
    • + *
  • The maximum duration that this account has funds to purchase.
    • + *
  • The configured MAX_AUTORENEW_PERIOD at the time of automatic + * renewal.
    • + *
+ * If this value is set, the referenced account MUST sign this + * transaction.
+ * If this value is set, the `adminKey` field MUST also be set (though that + * key MAY not have any correlation to this account). */ AccountID autoRenewAccount = 7; + + /** + * Access control for update or delete of custom fees. + *

+ * If set, subsequent `consensus_update_topic` transactions signed with this + * key MAY update or delete the custom fees for this topic.
+ * If not set, the custom fees for this topic SHALL BE immutable.
+ * If not set when the topic is created, this field CANNOT be set via + * update.
+ * If set when the topic is created, this field MAY be changed via update. + */ + Key fee_schedule_key = 8; + + /** + * A set of keys.
+ * Keys in this list are permitted to submit messages to this topic without + * paying custom fees associated with this topic. + *

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

+ * Each fee defined in this set SHALL be evaluated for + * each message submitted to this topic, and the resultant + * total assessed fees SHALL be charged.
+ * Custom fees defined here SHALL be assessed in addition to the base + * network and node fees.
+ * custom_fees list SHALL NOT contain more than + * `MAX_CUSTOM_FEE_ENTRIES_FOR_TOPICS` entries. + */ + repeated FixedCustomFee custom_fees = 10; } diff --git a/sdk/src/main/proto/consensus_delete_topic.proto b/sdk/src/main/proto/consensus_delete_topic.proto index 6b68113fd..035b2d238 100644 --- a/sdk/src/main/proto/consensus_delete_topic.proto +++ b/sdk/src/main/proto/consensus_delete_topic.proto @@ -1,13 +1,21 @@ +/** + * # Delete Topic + * Delete an existing topic from the Hedera Consensus Service (HCS). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,11 +36,22 @@ option java_multiple_files = true; import "basic_types.proto"; /** - * See [ConsensusService.deleteTopic()](#proto.ConsensusService) + * Delete a topic. + * + * Once deleted, subsequent transactions or queries for that topic SHALL NOT + * succeed.
+ * If adminKey is set on the topic, this transaction MUST be signed by that + * key.
+ * If adminKey is not set on the topic, this transaction SHALL fail with a + * response code of `UNAUTHORIZED`. A topic without an adminKey cannot be + * deleted (but MAY expire). + * + * ### Block Stream Effects + * None */ message ConsensusDeleteTopicTransactionBody { /** - * Topic identifier + * Topic to be deleted. */ TopicID topicID = 1; } diff --git a/sdk/src/main/proto/consensus_get_topic_info.proto b/sdk/src/main/proto/consensus_get_topic_info.proto index 408641f19..4fb262c0c 100644 --- a/sdk/src/main/proto/consensus_get_topic_info.proto +++ b/sdk/src/main/proto/consensus_get_topic_info.proto @@ -1,13 +1,21 @@ +/** + * # Get Topic + * Query a topic in the Hedera Consensus Service (HCS). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,38 +39,50 @@ import "response_header.proto"; import "consensus_topic_info.proto"; /** - * See [ConsensusService.getTopicInfo()](#proto.ConsensusService) + * Retrieve the latest state of a topic. + * + * This method is unrestricted and allowed on any topic by any payer + * account.
+ * A query for a deleted topic MAY succeed if the topic is within the + * "autorenew grace period".
+ * A query for a topic removed from state SHALL NOT succeed. */ message ConsensusGetTopicInfoQuery { /** - * Standard info sent from client to node, including the signed payment, and what kind of response is requested + * Standard information sent with every query operation.
+ * This includes 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 + * A topic ID. + *

+ * The network SHALL return information for this topic, if successful. */ TopicID topicID = 2; } /** - * Retrieve the parameters of and state of a consensus topic. + * Query response to describe the current state of a topic in the Hedera + * Consensus Service(HCS). */ message ConsensusGetTopicInfoResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither. + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * Topic identifier. + * The ID of the topic requested in the query. */ TopicID topicID = 2; /** - * Current state of the topic + * Information describing the current state of the topic. */ ConsensusTopicInfo topicInfo = 5; } diff --git a/sdk/src/main/proto/consensus_service.proto b/sdk/src/main/proto/consensus_service.proto index da1bfbf9c..573227861 100644 --- a/sdk/src/main/proto/consensus_service.proto +++ b/sdk/src/main/proto/consensus_service.proto @@ -1,13 +1,21 @@ +/** + * # Consensus Service API + * GRPC service definitions for the Hedera Consensus Service (HCS). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,93 +38,89 @@ import "transaction_response.proto"; import "transaction.proto"; /** - * The Consensus Service provides the ability for Hedera Hashgraph to provide aBFT consensus as to - * the order and validity of messages submitted to a *topic*, as well as a *consensus timestamp* for - * those messages. - * - * Automatic renewal can be configured via an autoRenewAccount. - * Any time an autoRenewAccount is added to a topic, that createTopic/updateTopic transaction must - * be signed by the autoRenewAccount. - * - * The autoRenewPeriod on an account must currently be set a value in createTopic between - * MIN_AUTORENEW_PERIOD (6999999 seconds) and MAX_AUTORENEW_PERIOD (8000001 seconds). During - * creation this sets the initial expirationTime of the topic (see more below). - * - * If no adminKey is on a topic, there may not be an autoRenewAccount on the topic, deleteTopic is - * not allowed, and the only change allowed via an updateTopic is to extend the expirationTime. - * - * If an adminKey is on a topic, every updateTopic and deleteTopic transaction must be signed by the - * adminKey, except for updateTopics which only extend the topic's expirationTime (no adminKey - * authorization required). - * - * If an updateTopic modifies the adminKey of a topic, the transaction signatures on the updateTopic - * must fulfill both the pre-update and post-update adminKey signature requirements. + * The Hedera Consensus Service (HCS) provides the ability for a 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. * - * Mirrornet ConsensusService may be used to subscribe to changes on the topic, including changes to - * the topic definition and the consensus ordering and timestamp of submitted messages. - * - * Until autoRenew functionality is supported by HAPI, the topic will not expire, the - * autoRenewAccount will not be charged, and the topic will not automatically be deleted. - * - * Once autoRenew functionality is supported by HAPI: - * - * 1. Once the expirationTime is encountered, if an autoRenewAccount is configured on the topic, the - * account will be charged automatically at the expirationTime, to extend the expirationTime of the - * topic up to the topic's autoRenewPeriod (or as much extension as the account's balance will - * supply). - * - * 2. If the topic expires and is not automatically renewed, the topic will enter the EXPIRED state. - * All transactions on the topic will fail with TOPIC_EXPIRED, except an updateTopic() call that - * modifies only the expirationTime. getTopicInfo() will succeed. This state will be available for - * a AUTORENEW_GRACE_PERIOD grace period (7 days). - * - * 3. After the grace period, if the topic's expirationTime is not extended, the topic will be - * automatically deleted and no transactions or queries on the topic will succeed after that point. */ service ConsensusService { /** - * Create a topic to be used for consensus. - * If an autoRenewAccount is specified, that account must also sign this transaction. - * If an adminKey is specified, the adminKey must sign the transaction. - * On success, the resulting TransactionReceipt contains the newly created TopicId. - * Request is [ConsensusCreateTopicTransactionBody](#proto.ConsensusCreateTopicTransactionBody) + * Create an HCS topic. + *

+ * On success, the resulting TransactionReceipt SHALL contain the newly + * created TopicId.
+ * If the `adminKey` is set on the topic, this transaction MUST be signed + * by that key.
+ * If the `adminKey` is _not_ set on the topic, this transaction MUST NOT + * set an `autoRenewAccount`. The new topic will be immutable and must be + * renewed manually.
+ * If the `autoRenewAccount` is set on the topic, this transaction MUST be + * signed by that account.
+ *

+ * The request body MUST be a + * [ConsensusCreateTopicTransactionBody](#proto.ConsensusCreateTopicTransactionBody) */ rpc createTopic (Transaction) returns (TransactionResponse); /** - * Update a topic. - * If there is no adminKey, the only authorized update (available to anyone) is to extend the expirationTime. - * Otherwise transaction must be signed by the adminKey. - * If an adminKey is updated, the transaction must be signed by the pre-update adminKey and post-update adminKey. - * If a new autoRenewAccount is specified (not just being removed), that account must also sign the transaction. - * Request is [ConsensusUpdateTopicTransactionBody](#proto.ConsensusUpdateTopicTransactionBody) + * Update an HCS topic. + *

+ * If the `adminKey` is not set on the topic, this transaction MUST extend + * the `expirationTime` and MUST NOT modify any other field.
+ * If the `adminKey` is set on the topic, this transaction MUST be signed + * by that key.
+ * If this transaction sets a new `adminKey`, this transaction MUST be + * signed by _both_ keys, the pre-update `adminKey` and + * the post-update `adminKey`.
+ * If this transaction sets a new, non-null, `autoRenewAccount`, the newly + * set account MUST sign this transaction.
+ *

+ * The request body MUST be a + * [ConsensusUpdateTopicTransactionBody](#proto.ConsensusUpdateTopicTransactionBody) */ rpc updateTopic (Transaction) returns (TransactionResponse); /** - * Delete a topic. No more transactions or queries on the topic (via HAPI) will succeed. - * If an adminKey is set, this transaction must be signed by that key. - * If there is no adminKey, this transaction will fail UNAUTHORIZED. - * Request is [ConsensusDeleteTopicTransactionBody](#proto.ConsensusDeleteTopicTransactionBody) + * Delete an HCS topic. + *

+ * If this transaction succeeds, all subsequent transactions referencing + * the deleted topic SHALL fail.
+ * The `adminKey` MUST be set on the topic and this transaction MUST be + * signed by that key.
+ * If the `adminKey` is not set on the topic, this transaction SHALL fail + * with a response code of `UNAUTHORIZED`. A topic without an `adminKey` + * cannot be deleted, but MAY expire.
+ *

+ * The request body MUST be a + * [ConsensusDeleteTopicTransactionBody](#proto.ConsensusDeleteTopicTransactionBody) */ rpc deleteTopic (Transaction) returns (TransactionResponse); /** - * Retrieve the latest state of a topic. This method is unrestricted and allowed on any topic by any payer account. - * Deleted accounts will not be returned. - * Request is [ConsensusGetTopicInfoQuery](#proto.ConsensusGetTopicInfoQuery) - * Response is [ConsensusGetTopicInfoResponse](#proto.ConsensusGetTopicInfoResponse) + * Submit a message to an HCS topic. + *

+ * Valid and authorized messages on valid topics will be ordered by the + * consensus service, published in the block stream, and available to all + * subscribers on this topic via the mirror nodes.
+ * If this transaction succeeds the resulting TransactionReceipt SHALL + * contain the latest topicSequenceNumber and topicRunningHash for the + * topic.
+ * If the topic has a `submitKey` then that key MUST sign this + * transaction.
+ *

+ * The request body MUST be a + * [ConsensusSubmitMessageTransactionBody](#proto.ConsensusSubmitMessageTransactionBody) */ - rpc getTopicInfo (Query) returns (Response); + rpc submitMessage (Transaction) returns (TransactionResponse); /** - * Submit a message for consensus. - * Valid and authorized messages on valid topics will be ordered by the consensus service, gossipped to the - * mirror net, and published (in order) to all subscribers (from the mirror net) on this topic. - * The submitKey (if any) must sign this transaction. - * On success, the resulting TransactionReceipt contains the topic's updated topicSequenceNumber and - * topicRunningHash. - * Request is [ConsensusSubmitMessageTransactionBody](#proto.ConsensusSubmitMessageTransactionBody) + * Retrieve the latest state of a topic. This method is unrestricted and + * allowed on any topic by any payer account. + *

+ * The request body MUST be a + * [ConsensusGetTopicInfoQuery](#proto.ConsensusGetTopicInfoQuery)
+ * The response body SHALL be a + * [ConsensusGetTopicInfoResponse](#proto.ConsensusGetTopicInfoResponse) */ - rpc submitMessage (Transaction) returns (TransactionResponse); + rpc getTopicInfo (Query) returns (Response); } diff --git a/sdk/src/main/proto/consensus_submit_message.proto b/sdk/src/main/proto/consensus_submit_message.proto index ece3155e9..366feae0a 100644 --- a/sdk/src/main/proto/consensus_submit_message.proto +++ b/sdk/src/main/proto/consensus_submit_message.proto @@ -1,13 +1,21 @@ +/** + * # Submit Message + * Submit a message to a topic via the Hedera Consensus Service (HCS). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,11 +36,22 @@ option java_multiple_files = true; import "basic_types.proto"; /** - * UNDOCUMENTED + * Consensus message "chunk" detail.
+ * This message carries information describing the way in which a message + * submitted for consensus is broken into multiple fragments to fit within + * network transaction size limits. + * + * The use of multiple message fragments is RECOMMENDED for any message + * greater than 4KiB in total size. + * + * ### Block Stream Effects + * None */ message ConsensusMessageChunkInfo { /** - * TransactionID of the first chunk, gets copied to every subsequent chunk in a fragmented message. + * The TransactionID of the first chunk. + *

+ * This MUST be set for every chunk in a fragmented message. */ TransactionID initialTransactionID = 1; @@ -43,13 +61,27 @@ message ConsensusMessageChunkInfo { int32 total = 2; /** - * The sequence number (from 1 to total) of the current chunk in the message. + * The sequence number (from 1 to total) of the current chunk + * in the message. */ int32 number = 3; } /** - * UNDOCUMENTED + * Submit a message for consensus.
+ * This transaction adds a new entry to the "end" of a topic, and provides + * the core function of the consensus service. + * + * Valid and authorized messages on valid topics SHALL be ordered by the + * consensus service, published in the block stream, and available to all + * subscribers on this topic via the mirror nodes.
+ * If this transaction succeeds the resulting `TransactionReceipt` SHALL contain + * the latest `topicSequenceNumber` and `topicRunningHash` for the topic.
+ * If the topic `submitKey` is set, and not an empty `KeyList`, then that key + * MUST sign this transaction. + * + * ### Block Stream Effects + * None */ message ConsensusSubmitMessageTransactionBody { /** @@ -58,12 +90,21 @@ message ConsensusSubmitMessageTransactionBody { TopicID topicID = 1; /** - * Message to be submitted. Max size of the Transaction (including signatures) is 6KiB. + * A message to be submitted. + *

+ * This Transaction (including signatures) MUST be less than 6KiB.
+ * Messages SHOULD be less than 4KiB. A "chunked" message MAY be submitted + * if a message larger than this is required. */ bytes message = 2; /** - * Optional information of the current chunk in a fragmented message. + * Information for the current "chunk" in a fragmented message. + *

+ * This value is REQUIRED if the full `message` is submitted in two or + * more fragments due to transaction size limits.
+ * If the message is submitted in a single transaction, then this + * field SHOULD NOT be set. */ ConsensusMessageChunkInfo chunkInfo = 3; } diff --git a/sdk/src/main/proto/consensus_topic_info.proto b/sdk/src/main/proto/consensus_topic_info.proto index 8a738b200..1d244ba40 100644 --- a/sdk/src/main/proto/consensus_topic_info.proto +++ b/sdk/src/main/proto/consensus_topic_info.proto @@ -1,13 +1,21 @@ +/** + * # Topic Information + * Query response describing a topic of the Hedera Consensus Service (HCS). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,64 +34,160 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; import "basic_types.proto"; +import "custom_fees.proto"; import "duration.proto"; import "timestamp.proto"; /** - * Current state of a topic. + * A query response describing the current state of a topic for the Hedera + * Consensus Service (HCS). */ message ConsensusTopicInfo { /** - * The memo associated with the topic (UTF-8 encoding max 100 bytes) + * A short description of this topic. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ 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. + * The latest running hash of the topic. + *

+ * This 48-byte field is the output of a SHA-384 digest with input + * data determined by the current version of the running hash algorithm + * used by the network.
+ * All new transactions SHALL use algorithm version `3`.
+ * The bytes of each uint64 or uint32 encoded for the hash input + * MUST be in Big-Endian format. + *

+ *

+ * If the algorithm version 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. + *
  2. The `topicRunningHashVersion` (8 bytes)
    3. + *
  3. The payer account's shard (8 bytes)
    4. + *
  4. The payer account's realm (8 bytes)
    5. + *
  5. The payer account's number (8 bytes)
    6. + *
  6. The topic's shard (8 bytes)
    7. + *
  7. The topic's realm (8 bytes)
    8. + *
  8. The topic's number (8 bytes)
    9. + *
  9. The number of seconds since the epoch when the + * `ConsensusSubmitMessage` reached consensus (8 bytes)
    10. + *
  10. The number of nanoseconds within the second when the + * `ConsensusSubmitMessage` reached consensus (4 bytes)
    11. + *
  11. The `topicSequenceNumber` (8 bytes)
    12. + *
  12. The output of a SHA-384 digest of the message bytes from the + * `ConsensusSubmitMessage` (48 bytes)
    13. + *
*/ bytes runningHash = 2; /** - * Sequence number (starting at 1 for the first submitMessage) of messages on the topic. + * A current sequence number (starting at 1 for the first message) + * for messages on this 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. + * An expiration time for this topic, in seconds since the epoch. + *

+ * For this purpose, `epoch` SHALL be the UNIX epoch + * with 0 at `1970-01-01T00:00:00.000Z`. */ Timestamp expirationTime = 4; /** - * Access control for update/delete of the topic. Null if there is no key. + * A key that MUST sign any transaction to update or delete this topic. + *

+ * If this value is not set (null) then the topic CANNOT be deleted, + * modified, or updated. */ Key adminKey = 5; /** - * Access control for ConsensusService.submitMessage. Null if there is no key. + * A key that MUST sign any transaction to submit a message to this topic. + *

+ * If this value is not set (null) then any account MAY submit messages to + * this topic. */ 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. + * A duration, in seconds, to extend the `expirationTime` value when + * this topic is automatically renewed. + *

+ * If the `autoRenewAccount` value for this topic is set to a valid account + * with sufficient HBAR balance to pay renewal fees when this topic + * expires, the system SHALL automatically renew this topic, extending the + * `expirationTime` value by the number of seconds described here.
+ * If, however, the `autoRenewAccount` lacks sufficient HBAR balance + * to pay renewal fees when this topic expires, this topic SHALL be + * deleted after the time period specified in the `AUTORENEW_GRACE_PERIOD` + * configuration value. */ Duration autoRenewPeriod = 7; /** - * The account, if any, to charge for automatic renewal of the topic's lifetime upon expiry. + * An account that is designated to pay automatic renewal fees. + *

+ * If this value is a valid account ID when this topic expires, + * this account SHALL be charged the renewal fees for this topic, + * if it holds sufficient HBAR balance. If the account does not hold + * sufficient HBAR balance to pay renewal fees when necessary, then + * this topic SHALL be deleted.
+ * If this value is not set (null), or is not a valid account ID, when + * this topic expires, then this topic SHALL be deleted after the time + * period specified in the `AUTORENEW_GRACE_PERIOD` configuration value. */ AccountID autoRenewAccount = 8; /** - * The ledger ID the response was returned from; please see HIP-198 for the network-specific IDs. + * A ledger ID of the network that generated this response. + *

+ * This value SHALL identify the distributed ledger that responded to + * this query. */ bytes ledger_id = 9; + + /** + * Access control for update/delete of custom fees. + *

+ * If unset, custom fees CANNOT be set for this topic.
+ * If not set when the topic is created, this field CANNOT be set via + * update.
+ * If set when the topic is created, this field MAY be changed via update. + */ + Key fee_schedule_key = 10; + + /** + * A set of keys.
+ * Keys in this list are permitted to submit messages to this topic without + * paying custom fees associated with this topic. + *

+ * If a topic submit message is signed by _any_ key included in this set, + * custom fees SHALL NOT be charged for that transaction.
+ * `fee_exempt_key_list` MAY contain keys for accounts that are inactive, + * deleted, or non-existent.
+ * If not set, there SHALL NOT be any fee-exempt keys. In particular, the + * following keys SHALL NOT be implicitly or automatically added to this + * list: `adminKey`, `submitKey`, `fee_schedule_key`. + * A `fee_exempt_key_list` MUST NOT contain more than + * `MAX_ENTRIES_FOR_FEE_EXEMPT_KEY_LIST` keys. + * A `fee_exempt_key_list` MUST NOT contain any duplicate keys. + */ + repeated Key fee_exempt_key_list = 11; + + /** + * A set of custom fee definitions.
+ * These are fees to be assessed for each submit to this topic. + *

+ * Each fee defined in this set SHALL be evaluated for + * each message submitted to this topic, and the resultant + * total assessed fees SHALL be charged.
+ * Custom fees defined here SHALL be assessed in addition to the base + * network and node fees. + */ + repeated FixedCustomFee custom_fees = 12; } diff --git a/sdk/src/main/proto/consensus_update_topic.proto b/sdk/src/main/proto/consensus_update_topic.proto index 7a1acf9c4..5a03102f1 100644 --- a/sdk/src/main/proto/consensus_update_topic.proto +++ b/sdk/src/main/proto/consensus_update_topic.proto @@ -1,13 +1,21 @@ +/** + * # Update Topic + * Update a topic for the Hedera Consensus Service (HCS). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -28,63 +35,151 @@ option java_multiple_files = true; import "google/protobuf/wrappers.proto"; import "basic_types.proto"; +import "custom_fees.proto"; import "duration.proto"; import "timestamp.proto"; /** - * All fields left null will not be updated. - * See [ConsensusService.updateTopic()](#proto.ConsensusService) + * Update the fields of an existing HCS topic. + * + * The topicID field is REQUIRED. All other fields are OPTIONAL.
+ * Fields set on this transaction SHALL be updated.
+ * Fields _not_ set on this transaction SHALL NOT be updated. + * + * ### Block Stream Effects + * None */ message ConsensusUpdateTopicTransactionBody { /** - * UNDOCUMENTED + * The topic ID specifying the topic to update. + *

+ * A topic with this ID MUST exist and MUST NOT be deleted.
+ * This value is REQUIRED. */ TopicID topicID = 1; /** - * If set, the new memo to be associated with the topic (UTF-8 encoding max 100 bytes) + * An updated memo to be associated with this topic. + *

+ * If this value is set, the current `adminKey` for the topic MUST sign + * this transaction.
+ * This value, if set, SHALL be encoded UTF-8 and SHALL NOT exceed + * 100 bytes when so encoded. */ 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. + * An updated expiration time for this topic, in seconds since the epoch. + *

+ * For this purpose, `epoch` SHALL be the UNIX epoch + * with 0 at `1970-01-01T00:00:00.000Z`.
+ * The expirationTime MUST NOT be greater than the sum of + * `MAX_AUTORENEW_PERIOD` and the actual consensus timestamp of + * this transaction.
+ * If `adminKey` is unset for the _topic_, this transaction MUST NOT + * modify any other field. */ Timestamp expirationTime = 4; /** - * Access control for update/delete of the topic. - * If unspecified, no change. - * If empty keyList - the adminKey is cleared. + * Updated access control for modification of the topic. + *

+ * If this field is set, that key and the previously set key MUST both + * sign this transaction.
+ * If this value is an empty `KeyList`, the prior key MUST sign this + * transaction, and the topic SHALL be immutable after this transaction + * completes, except for expiration and renewal. */ Key adminKey = 6; /** - * Access control for ConsensusService.submitMessage. - * If unspecified, no change. - * If empty keyList - the submitKey is cleared. + * Updated access control for message submission to the topic. + *

+ * If this value is set, the current `adminKey` for the topic MUST sign + * this transaction.
+ * If this value is set to an empty `KeyList`, the `submitKey` for the + * topic will be unset after this transaction completes. When the + * `submitKey` is unset, any account may submit a message on the topic, + * without restriction. */ 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. + * An updated value for the number of seconds by which the topic expiration + * will be automatically extended upon expiration, if it has a valid + * auto-renew account. + *

+ * If this value is set, the current `adminKey` for the topic MUST sign + * this transaction.
+ * This value, if set, MUST be greater than the + * configured MIN_AUTORENEW_PERIOD.
+ * This value, if set, MUST be less than the + * configured MAX_AUTORENEW_PERIOD. */ 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. + * An updated ID for the account to be charged renewal fees at the topic's + * `expirationTime` to extend the lifetime of the topic. + *

+ * If this value is set and not the "sentinel account", the referenced + * account MUST sign this transaction.
+ * If this value is set, the current `adminKey` for the topic MUST sign + * this transaction.
+ * If this value is set to the "sentinel account", which is `0.0.0`, the + * `autoRenewAccount` SHALL be removed from the topic. */ AccountID autoRenewAccount = 9; + + /** + * Access control for update/delete of custom fees. + *

+ * If set, subsequent consensus_update_topic transactions signed with this + * key MAY update or delete the custom fees for this topic.
+ * If this field is set, the admin key MUST sign this transaction.
+ * If this field is set, the previous value SHALL be replaced.
+ * If set to a 'Key' containing an empty 'KeyList', the previous value + * SHALL be cleared.
+ * If not set, the current key SHALL NOT change.
+ * If unset in state, this field MUST NOT be set in this transaction.
+ * If not set when the topic is created, this field CANNOT be set via + * update.
+ */ + Key fee_schedule_key = 10; + + /** + * A set of keys
+ * Keys in this list are permitted to submit messages to this topic without + * paying custom fees associated with this topic. + *

+ * If a submit transaction is signed by _any_ key included in this set, + * custom fees SHALL NOT be charged for that transaction.
+ * If this field is not set, the current set of keys SHALL NOT change.
+ * If this field is set, but contains an empty list, any existing fee-exempt + * keys SHALL be removed.
+ * A `fee_exempt_key_list` MUST NOT contain more than + * `MAX_ENTRIES_FOR_FEE_EXEMPT_KEY_LIST` keys.
+ * A `fee_exempt_key_list` MUST NOT contain any duplicate keys.
+ * A `fee_exempt_key_list` MAY contain keys for accounts that are inactive, + * deleted, or non-existent. + */ + FeeExemptKeyList fee_exempt_key_list = 11; + + /** + * A set of custom fee definitions.
+ * These are fees to be assessed for each submit to this topic. + *

+ * Each fee defined in this set SHALL be evaluated for + * each message submitted to this topic, and the resultant + * total assessed fees SHALL be charged.
+ * Custom fees defined here SHALL be assessed in addition to the base + * network and node fees.
+ * If this field is not set, the current set of custom fees + * SHALL NOT change.
+ * If this field is set, but contains an empty list, all current custom fees + * SHALL be removed. + * custom_fees list SHALL NOT contain more than + * `MAX_CUSTOM_FEE_ENTRIES_FOR_TOPICS` entries. + */ + FixedCustomFeeList custom_fees = 12; } diff --git a/sdk/src/main/proto/contract_call.proto b/sdk/src/main/proto/contract_call.proto index 9000e339c..069648605 100644 --- a/sdk/src/main/proto/contract_call.proto +++ b/sdk/src/main/proto/contract_call.proto @@ -1,13 +1,21 @@ +/** + * # Contract Call + * Transaction body for calls to a Smart Contract. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,35 +36,52 @@ 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. + * Call a function of a given smart contract, providing function parameter + * inputs as needed. * - * If this function results in data being stored, an amount of gas is calculated that reflects this - * storage burden. + * Resource ("gas") charges SHALL include all relevant fees incurred by the + * contract execution, including any storage required.
+ * The total transaction fee SHALL incorporate all of the "gas" actually + * consumed as well as the standard fees for transaction handling, data + * transfers, signature verification, etc...
+ * The response SHALL contain the output returned by the function call. * - * 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. + * ### Block Stream Effects + * A `CallContractOutput` message SHALL be emitted for each transaction. */ message ContractCallTransactionBody { /** - * The contract to call + * The ID of a smart contract to call. */ ContractID contractID = 1; /** - * the maximum amount of gas to use for the call + * A maximum limit to the amount of gas to use for this call. + *

+ * The network SHALL charge the greater of the following, but + * SHALL NOT charge more than the value of this field. + *

    + *
  1. The actual gas consumed by the smart contract call.
    2. + *
  2. `80%` of this value.
    3. + *
+ * The `80%` factor encourages reasonable estimation, while allowing for + * some overage to ensure successful execution. */ int64 gas = 2; /** - * number of tinybars sent (the function must be payable if this is nonzero) + * An amount of tinybar sent via this contract call. + *

+ * If this is non-zero, the function MUST be `payable`. */ int64 amount = 3; /** - * which function to call, and the parameters to pass to the function + * The smart contract function to call. + *

+ * This MUST contain The application binary interface (ABI) encoding of the + * function call per the Ethereum contract ABI standard, giving the + * function signature and arguments being passed to the function. */ bytes functionParameters = 4; } diff --git a/sdk/src/main/proto/contract_call_local.proto b/sdk/src/main/proto/contract_call_local.proto index 49bb5b503..83da2066b 100644 --- a/sdk/src/main/proto/contract_call_local.proto +++ b/sdk/src/main/proto/contract_call_local.proto @@ -1,13 +1,22 @@ +/** + * # Local Contract Call + * A Contract Call executed directly on the current node + * (that is, without consensus). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2022 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,213 +35,100 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; import "basic_types.proto"; +import "contract_types.proto"; import "query_header.proto"; import "response_header.proto"; -import "contract_types.proto"; - -import "google/protobuf/wrappers.proto"; - -/** - * The log information for an event returned by a smart contract function call. One function call - * may return several such events. - */ -message ContractLoginfo { - /** - * 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. - */ -message ContractFunctionResult { - /** - * 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; - - /** - * [DEPRECATED] the list of smart contracts that were created by the function call. - * - * The created ids will now _also_ be externalized through internal transaction - * records, where each record has its alias field populated with the new contract's - * EVM address. (This is needed for contracts created with CREATE2, since - * there is no longer a simple relationship between the new contract's 0.0.X id - * and its Solidity address.) - */ - repeated ContractID createdContractIDs = 7 [deprecated=true]; - - reserved 8; - - /** - * The new contract's 20-byte EVM address. Only populated after release 0.23, - * where each created contract will have its own record. (This is an important - * point--the field is not repeated because there will be a separate - * child record for each created contract.) - * - * Every contract has an EVM address determined by its shard.realm.num id. - * This address is as follows: - *

    - *
  1. The first 4 bytes are the big-endian representation of the shard.
    2. - *
  2. The next 8 bytes are the big-endian representation of the realm.
    3. - *
  3. The final 8 bytes are the big-endian representation of the number.
    4. - *
- * - * Contracts created via CREATE2 have an additional, primary address that is - * derived from the EIP-1014 - * specification, and does not have a simple relation to a shard.realm.num id. - * - * (Please do note that CREATE2 contracts can also be referenced by the three-part - * EVM address described above.) - */ - google.protobuf.BytesValue evm_address = 9; - - /** - * The amount of gas available for the call, aka the gasLimit. - * - * This field should only be populated when the paired TransactionBody in the record stream is not a - * ContractCreateTransactionBody or a ContractCallTransactionBody. - */ - int64 gas = 10; - - /** - * Number of tinybars sent (the function must be payable if this is nonzero). - * - * This field should only be populated when the paired TransactionBody in the record stream is not a - * ContractCreateTransactionBody or a ContractCallTransactionBody. - */ - int64 amount = 11; - - /** - * The parameters passed into the contract call. - * - * This field should only be populated when the paired TransactionBody in the record stream is not a - * ContractCreateTransactionBody or a ContractCallTransactionBody. - */ - bytes functionParameters = 12; - - /** - * The account that is the "sender." If not present it is the accountId from the transactionId. - * - * This field should only be populated when the paired TransactionBody in the record stream is not a - * ContractCreateTransactionBody or a ContractCallTransactionBody. - */ - AccountID sender_id = 13; - - /** - * A list of updated contract account nonces containing the new nonce value for each contract account. - * This is always empty in a ContractCallLocalResponse#ContractFunctionResult message, since no internal creations can happen in a static EVM call. - */ - repeated ContractNonceInfo contract_nonces = 14; - - /** - * If not null this field specifies what the value of the signer account nonce is post transaction execution. - * For transactions that don't update the signer nonce, this field should be null. - */ - google.protobuf.Int64Value signer_nonce = 15; -} /** - * 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. + * Call a view function of a given smart contract
+ * The call must provide function parameter inputs as needed.
+ * This is potentially useful for calling view functions that will not revert + * when executed in a static EVM context. Many such use cases will be better + * served by using a Mirror Node API, however. * - * Unlike a ContractCall transaction, the node will consume the entire amount of provided gas in determining - * the fee for this query. + * This is performed locally on the particular node that the client is + * communicating with. Executing the call locally is faster and less costly, + * but imposes certain restrictions.
+ * The call MUST NOT change the state of the contract instance. This also + * precludes any expenditure or transfer of HBAR or other tokens.
+ * The call SHALL NOT have a separate consensus timestamp.
+ * The call SHALL NOT generate a record nor a receipt.
+ * The response SHALL contain the output returned by the function call.
+ * Any contract call that would use the `STATICCALL` opcode MAY be called via + * contract call local with performance and cost benefits. + * + * Unlike a ContractCall transaction, the node SHALL always consume the + * _entire_ amount of offered "gas" in determining the fee for this query, so + * accurate gas estimation is important. */ message ContractCallLocalQuery { /** - * 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. + * Standard information sent with every query operation.
+ * This includes the signed payment and what kind of response is requested + * (cost, state proof, both, or neither). + *

+ * The payment MUST be sufficient for the base fees _and_ the full amount + * in the `gas` field. */ QueryHeader header = 1; /** - * The contract to make a static call against + * The ID of a smart contract to call. */ 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 + * The amount of "gas" to use for this call. + *

+ * This transaction SHALL consume all of the gas offered and charge the + * corresponding fee according to the current exchange rate between + * HBAR and "gas". */ int64 gas = 3; /** - * which function to call, and the parameters to pass to the function + * The smart contract function to call, and the parameters to pass to that + * function. + *

+ * These SHALL be presented in EVM bytecode function call format. */ 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. + * Do not use this field; it is ignored in the current software. + *

+ * The maximum number of bytes that the result might include.
+ * The call will fail if it would have returned more than this number + * of bytes. */ - int64 maxResultSize = 5 [deprecated=true]; - + int64 maxResultSize = 5 [deprecated = true]; /** - * The account that is the "sender." If not present it is the accountId from the transactionId. - * Typically a different value than specified in the transactionId requires a valid signature - * over either the hedera transaction or foreign transaction data. + * The account that is the "sender" for this contract call. + *

+ * If this is not set it SHALL be interpreted as the accountId from the + * associated transactionId.
+ * If this is set then either the associated transaction or the foreign + * transaction data MUST be signed by the referenced account. */ AccountID sender_id = 6; } /** - * Response when the client sends the node ContractCallLocalQuery + * The response returned by a `ContractCallLocalQuery` transaction. */ message ContractCallLocalResponse { /** - * standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * the value returned by the function (if it completed and didn't fail) + * The result(s) returned by the function call, if successful. + *

+ * If the call failed this value SHALL be unset. */ ContractFunctionResult functionResult = 2; } diff --git a/sdk/src/main/proto/contract_create.proto b/sdk/src/main/proto/contract_create.proto index 7ff8ae808..9650ac509 100644 --- a/sdk/src/main/proto/contract_create.proto +++ b/sdk/src/main/proto/contract_create.proto @@ -1,13 +1,46 @@ +/** + * # Smart Contract Create + * + * Create a new smart contract. + * + * ## General Comments + * - A smart contract 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 characteristic + * is generally true if the contract instance was created without a value + * for the `adminKey` field. For some uses, however, it may 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 `adminKey` is set to a valid Key (which MAY be complex), then a + * transaction that can change the state of the smart contract in arbitrary + * ways MAY be signed with enough signatures to activate that Key. Such + * transactions might reverse a transaction, change the code to close an + * unexpected loophole, remove an exploit, or adjust outputs in ways not + * covered by the code itself. The admin key MAY also be used to change the + * autoRenewPeriod, and change the adminKey field itself (for example, to + * remove that key after a suitable testing period). The API currently does + * not implement all relevant capabilities. But it does allow the `adminKey` + * field to be set and queried, and MAY implement further administrative + * capability in future releases. + * - The current API ignores shardID, realmID, and newRealmAdminKey, and + * creates everything in shard 0 and realm 0. Future versions of the system + * MAY support additional shards and realms. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +52,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -30,177 +62,229 @@ 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, either stored in a previously created file or in the transaction body itself for - * small contracts. - * - * - * 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. + * Create a new smart contract. * - * - 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 transaction succeeds, the `ContractID` for the new smart contract + * SHALL be set in the transaction receipt.
+ * The contract is defined by the initial bytecode (or `initcode`). The + * `initcode` SHALL be stored either in a previously created file, or in the + * transaction body itself for very small contracts. * - * - 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. + * As part of contract creation, the constructor defined for the new smart + * contract SHALL run with the parameters provided in the + * `constructorParameters` field.
+ * The gas to "power" that constructor MUST be provided via the `gas` field, + * and SHALL be charged to the payer for this transaction.
+ * If the contract _constructor_ stores information, it is charged gas for that + * storage. There is a separate fee in HBAR to maintain that storage until the + * expiration, and that fee SHALL be added to this transaction as part of the + * _transaction fee_, rather than gas. * - * - 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 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. - * - * Signing requirements: If an admin key is set, it must sign the transaction. If an - * auto-renew account is set, its key must sign the transaction. + * ### Block Stream Effects + * A `CreateContractOutput` message SHALL be emitted for each transaction. */ message ContractCreateTransactionBody { - /** - * There are two ways to specify the initcode of a ContractCreateTransction. If the initcode is - * large (> 5K) then it must be stored in a file as hex encoded ascii. If it is small then it may - * either be stored as a hex encoded file or as a binary encoded field as part of the transaciton. - * - */ oneof initcodeSource { /** - * The file containing the smart contract initcode. A copy will be made and held by the - * contract instance, and have the same expiration time as the instance. + * The source for the smart contract EVM bytecode. + *

+ * The file containing the smart contract initcode. + * A copy of the contents SHALL be made and held as `bytes` + * in smart contract state.
+ * The contract bytecode is limited in size only by the + * network file size limit. */ FileID fileID = 1; /** - * The bytes of the smart contract initcode. This is only useful if the smart contract init - * is less than the hedera transaction limit. In those cases fileID must be used. + * The source for the smart contract EVM bytecode. + *

+ * The bytes of the smart contract initcode. A copy of the contents + * SHALL be made and held as `bytes` in smart contract state.
+ * This value is limited in length by the network transaction size + * limit. This entire transaction, including all fields and signatures, + * MUST be less than the network transaction size limit. */ bytes initcode = 16; } /** - * 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. + * Access control for modification of the smart contract after + * it is created. + *

+ * If this field is set, that key MUST sign this transaction.
+ * If this field is set, that key MUST sign each future transaction to + * update or delete the contract.
+ * An updateContract transaction that _only_ extends the topic + * expirationTime (a "manual renewal" transaction) SHALL NOT require + * admin key signature. + *

+ * A contract without an admin key SHALL be immutable, except for + * expiration and renewal. */ Key adminKey = 3; /** - * gas to run the constructor + * A maximum limit to the amount of gas to use for the constructor call. + *

+ * The network SHALL charge the greater of the following, but SHALL NOT + * charge more than the value of this field. + *

    + *
  1. The actual gas consumed by the smart contract + * constructor call.
    2. + *
  2. `80%` of this value.
    3. + *
+ * The `80%` factor encourages reasonable estimation, while allowing for + * some overage to ensure successful execution. */ int64 gas = 4; /** - * initial number of tinybars to put into the cryptocurrency account associated with and owned - * by the smart contract + * The amount of HBAR to use as an initial balance for the account + * representing the new smart contract. + *

+ * This value is presented in tinybar + * (10-8 HBAR).
+ * The HBAR provided here will be withdrawn from the payer account that + * signed this transaction. */ int64 initialBalance = 5; /** - * [Deprecated] 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. + * Proxy account staking is handled via `staked_id`. + *

+ * Former field to designate a proxy account for HBAR staking. + * This field MUST NOT be set. */ AccountID proxyAccountID = 6 [deprecated = true]; /** - * the instance will charge its account every this many seconds to renew for this long + * The initial lifetime, in seconds, for the smart contract, and the number + * of seconds for which the smart contract will be automatically renewed + * upon expiration. + *

+ * This value MUST be set.
+ * This value MUST be greater than the configured MIN_AUTORENEW_PERIOD.
+ * This value MUST be less than the configured MAX_AUTORENEW_PERIOD.
*/ Duration autoRenewPeriod = 8; /** - * parameters to pass to the constructor + * An array of bytes containing the EVM-encoded parameters to pass to + * the smart contract constructor defined in the smart contract init + * code provided. */ bytes constructorParameters = 9; /** - * shard in which to create this + *

Review Question
+ *
Should this be deprecated?
+ * It's never been used and probably never should be used...
+ * Shard should be determined by the node the transaction is submitted to. + *
+ *

+ * The shard in which to create the new smart contract.
+ * This value is currently ignored. */ ShardID shardID = 10; /** - * realm in which to create this (leave this null to create a new realm) + *

Review Question
+ *
Should this be deprecated?
+ * It's never been used and probably never should be used...
+ * Realm should be determined by node and network parameters. + *
+ *

+ * The shard/realm in which to create the new smart contract.
+ * This value is currently ignored. */ RealmID realmID = 11; /** - * if realmID is null, then this the admin key for the new realm that will be created + *

Review Question
+ *
Should this be deprecated?
+ * It's never been used and probably never should be used...
+ * If a realm is used, it must already exist; we shouldn't be creating it + * without a separate transaction.
+ *

+ * This was intended to provide an admin key for any new realm created + * during the creation of the smart contract.
+ * This value is currently ignored. a new realm SHALL NOT be created, + * regardless of the value of `realmID`. */ Key newRealmAdminKey = 12; /** - * the memo that was submitted as part of the contract (max 100 bytes) + * A short memo for this smart contract. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 13; /** - * The maximum number of tokens that can be auto-associated with the contract.
- * If this is less than or equal to `used_auto_associations`, or 0, then this contract - * MUST manually associate with a token before transacting in that token.
- * This value MAY also be `-1` to indicate no limit.
- * This value MUST NOT be less than `-1`.
- * By default this value is 0 for contracts. + * The maximum number of tokens that can be auto-associated with this + * smart contract. + *

+ * If this is less than or equal to `used_auto_associations` (or 0), then + * this contract MUST manually associate with a token before transacting + * in that token.
+ * Following HIP-904 This value may also be `-1` to indicate no limit.
+ * This value MUST NOT be less than `-1`. */ int32 max_automatic_token_associations = 14; /** - * An account to charge for auto-renewal of this contract. If not set, or set to an - * account with zero hbar balance, the contract's own hbar balance will be used to - * cover auto-renewal fees. + * The id of an account, in the same shard and realm as this smart + * contract, that has signed this transaction, allowing the network to use + * its balance, when needed, to automatically extend this contract's + * expiration time. + *

+ * If this field is set, that key MUST sign this transaction.
+ * If this field is set, then the network SHALL deduct the necessary fees + * from the designated auto renew account, if that account has sufficient + * balance. If the auto renew account does not have sufficient balance, + * then the fees for contract renewal SHALL be deducted from the HBAR + * balance held by the smart contract.
+ * If this field is not set, then all renewal fees SHALL be deducted from + * the HBAR balance held by this contract. */ AccountID auto_renew_account_id = 15; - /** - * ID of the new account or node to which this contract is staking. - */ oneof staked_id { /** - * ID of the account to which this contract is staking. + * An account ID. + *

+ * This smart contract SHALL stake its HBAR via this account as proxy. */ AccountID staked_account_id = 17; /** - * ID of the node this contract is staked to. + * The ID of a network node. + *

+ * This smart contract SHALL stake its HBAR to this node. + *

+ *

Note: node IDs do fluctuate as node operators change. + * Most contracts are immutable, and a contract staking to an invalid + * node ID SHALL NOT participate in staking. Immutable contracts MAY + * find it more reliable to use a proxy account for staking + * (via `staked_account_id`) to enable updating the _effective_ staking + * node ID when necessary through updating the proxy + * account.
*/ int64 staked_node_id = 18; } /** - * If true, the contract declines receiving a staking reward. The default value is false. + * A flag indicating that this smart contract declines to receive any + * reward for staking its HBAR balance to help secure the network. + *

+ * If set to true, this smart contract SHALL NOT receive any reward for + * staking its HBAR balance to help secure the network, regardless of + * staking configuration, but MAY stake HBAR to support the network + * without reward. */ bool decline_reward = 19; } diff --git a/sdk/src/main/proto/contract_delete.proto b/sdk/src/main/proto/contract_delete.proto index 0cd8ab5ca..a2637ab01 100644 --- a/sdk/src/main/proto/contract_delete.proto +++ b/sdk/src/main/proto/contract_delete.proto @@ -1,13 +1,22 @@ +/** + * # Contract Delete + * Delete a smart contract, transferring any remaining balance to a + * designated account. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,8 +28,8 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ + option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; @@ -28,41 +37,66 @@ 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. + * Delete a smart contract, and transfer any remaining HBAR balance to a + * designated account. + * + * If this call succeeds then all subsequent calls to that smart contract + * SHALL execute the `0x0` opcode, as required for EVM equivalence. * - * If the target contract is immutable (that is, was created without an admin key), then this - * transaction resolves to MODIFYING_IMMUTABLE_CONTRACT. + * ### Requirements + * - An account or smart contract MUST be designated to receive all remaining + * account balances. + * - The smart contract MUST have an admin key set. If the contract does not + * have `admin_key` set, then this transaction SHALL fail and response code + * `MODIFYING_IMMUTABLE_CONTRACT` SHALL be set. + * - If `admin_key` is, or contains, an empty `KeyList` key, it SHALL be + * treated the same as an admin key that is not set. + * - The `Key` set for `admin_key` on the smart contract MUST have a valid + * signature set on this transaction. + * - The designated receiving account MAY have `receiver_sig_required` set. If + * that field is set, the receiver account MUST also sign this transaction. + * - The field `permanent_removal` MUST NOT be set. That field is reserved for + * internal system use when purging the smart contract from state. Any user + * transaction with that field set SHALL be rejected and a response code + * `PERMANENT_REMOVAL_REQUIRES_SYSTEM_INITIATION` SHALL be set. * - * --- 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 + * ### Block Stream Effects + * None */ message ContractDeleteTransactionBody { /** - * The id of the contract to be deleted + * The id of the contract to be deleted. + *

+ * This field is REQUIRED. */ ContractID contractID = 1; oneof obtainers { /** - * The id of an account to receive any remaining hBars from the deleted contract + * An Account ID recipient. + *

+ * This account SHALL receive all HBAR and other tokens still owned by + * the contract that is removed. */ - AccountID transferAccountID = 2; + AccountID transferAccountID = 2; /** - * The id of a contract to receive any remaining hBars from the deleted contract + * A contract ID recipient. + *

+ * This contract SHALL receive all HBAR and other tokens still owned by + * the contract that is removed. */ - ContractID transferContractID = 3; + ContractID transferContractID = 3; } /** - * If set to true, means this is a "synthetic" system transaction being used to - * alert mirror nodes that the contract is being permanently removed from the ledger. - * IMPORTANT: User transactions cannot set this field to true, as permanent - * removal is always managed by the ledger itself. Any ContractDeleteTransactionBody - * submitted to HAPI with permanent_removal=true will be rejected with precheck status - * PERMANENT_REMOVAL_REQUIRES_SYSTEM_INITIATION. + * A flag indicating that this transaction is "synthetic"; initiated by the + * node software. + *

+ * The consensus nodes create such "synthetic" transactions to both to + * properly manage state changes and to communicate those changes to other + * systems via the Block Stream.
+ * A user-initiated transaction MUST NOT set this flag. */ bool permanent_removal = 4; } diff --git a/sdk/src/main/proto/contract_get_bytecode.proto b/sdk/src/main/proto/contract_get_bytecode.proto index ba6224ecc..5193caeaa 100644 --- a/sdk/src/main/proto/contract_get_bytecode.proto +++ b/sdk/src/main/proto/contract_get_bytecode.proto @@ -1,13 +1,21 @@ +/** + * # Get Contract Bytecode + * A standard query to read the current bytecode for a smart contract. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,34 +38,38 @@ import "query_header.proto"; import "response_header.proto"; /** - * Get the runtime bytecode for a smart contract instance + * A transaction body to request the current bytecode for a smart contract. */ message ContractGetBytecodeQuery { /** - * 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 information sent with every query operation.
+ * This includes 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 + * A smart contract ID. + *

+ * The network SHALL return bytecode for this smart contract, if successful. */ ContractID contractID = 2; } /** - * Response when the client sends the node ContractGetBytecodeQuery + * Information returned in response to a "get bytecode" query for a + * smart contract. */ message ContractGetBytecodeResponse { /** - * standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * the runtime bytecode of the contract + * The current bytecode of the requested smart contract. */ bytes bytecode = 6; } - diff --git a/sdk/src/main/proto/contract_get_info.proto b/sdk/src/main/proto/contract_get_info.proto index 0dda491eb..99985d3d6 100644 --- a/sdk/src/main/proto/contract_get_info.proto +++ b/sdk/src/main/proto/contract_get_info.proto @@ -1,13 +1,21 @@ +/** + * # Contract Get Info + * A standard query to obtain detailed information about a smart contract. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -33,126 +40,142 @@ 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 initcode (if a file was used to initialize the contract), and the time when it will expire. + * Request detailed information about a smart contract. */ message ContractGetInfoQuery { /** - * 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 information sent with every query operation.
+ * This includes 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 + * A smart contract ID. + *

+ * The network SHALL return information for this smart contract, + * if successful. */ ContractID contractID = 2; } /** - * Response when the client sends the node ContractGetInfoQuery + * Information returned in response to a "get info" query for a smart contract. */ message ContractGetInfoResponse { /** - * standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; + /** + * The information, as requested, for a smart contract. + * A state proof MAY be generated for this value. + */ + ContractInfo contractInfo = 2; + message ContractInfo { /** - * ID of the contract instance, in the format used in transactions + * The ID of the smart contract requested in the query. */ ContractID contractID = 1; /** - * ID of the cryptocurrency account owned by the contract instance, in the format used in - * transactions + * The Account ID for the account entry associated with this + * smart contract. */ AccountID accountID = 2; /** - * ID of both the contract instance and the cryptocurrency account owned by the contract - * instance, in the format used by Solidity + * The "Solidity" form contract ID.
+ * This is a hexadecimal string form of the 20-byte EVM address + * of the contract. */ 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. + * The key that MUST sign any transaction to update or modify this + * smart contract. + *

+ * If this value is null, or is an empty `KeyList` then the contract + * CANNOT be deleted, modified, or updated, but MAY still expire. */ Key adminKey = 4; /** - * the current time at which this contract instance (and its account) is set to expire + * The point in time at which this contract will 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. + * The duration, in seconds, for which the contract lifetime will be + * automatically extended upon expiration, provide sufficient HBAR is + * available at that time to pay the renewal fee.
+ * See `auto_renew_account_id` for additional conditions. */ Duration autoRenewPeriod = 6; /** - * number of bytes of storage being used by this instance (which affects the cost to extend - * the expiration time) + * The amount of storage used by this smart contract. */ int64 storage = 7; /** - * the memo associated with the contract (max 100 bytes) + * A short description of this smart contract. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 8; /** - * The current balance, in tinybars + * The current HBAR balance, in tinybar, of the smart contract account. */ uint64 balance = 9; /** - * Whether the contract has been deleted + * A flag indicating that this contract is deleted. */ bool deleted = 10; /** - * [DEPRECATED] The metadata of the tokens associated to the contract. This field was - * deprecated by HIP-367, which allowed - * an account to be associated to an unlimited number of tokens. This scale makes it more - * efficient for users to consult mirror nodes to review their token associations. + * Because HIP-367, + * which allows an account to be associated to an unlimited number of + * tokens, it became necessary to only provide this information from + * a Mirror Node.
+ * The list of tokens associated to this contract. */ repeated TokenRelationship tokenRelationships = 11 [deprecated = true]; /** - * The ledger ID the response was returned from; please see HIP-198 for the network-specific IDs. + * The ledger ID of the network that generated this response. + *

+ * This value SHALL identify the distributed ledger that responded to + * this query. */ bytes ledger_id = 12; /** - * ID of the an account to charge for auto-renewal of this contract. If not set, or set to an account with zero hbar - * balance, the contract's own hbar balance will be used to cover auto-renewal fees. + * An account designated to pay the renewal fee upon automatic renewal + * of this contract. + *

+ * If this is not set, or is set to an account with zero HBAR + * available, the HBAR balance of the contract, if available, + * SHALL be used to pay the renewal fee. */ AccountID auto_renew_account_id = 13; /** - * The maximum number of tokens that a contract can be implicitly associated with. + * The maximum number of tokens that the contract can be + * associated to automatically. */ int32 max_automatic_token_associations = 14; /** - * Staking metadata for this contract. + * Staking information for this contract. */ StakingInfo staking_info = 15; } - - /** - * the information about this contract instance (a state proof can be generated for this) - */ - ContractInfo contractInfo = 2; } - diff --git a/sdk/src/main/proto/contract_get_records.proto b/sdk/src/main/proto/contract_get_records.proto index b4d68fab9..fd35c4f42 100644 --- a/sdk/src/main/proto/contract_get_records.proto +++ b/sdk/src/main/proto/contract_get_records.proto @@ -1,13 +1,25 @@ +/** + * # Get contract records + * Deprecated query messages to read all recent contract transaction records. + * + * > REVIEW QUESTION + * >> Can we delete this file and remove the related query entirely? + * >> It appears it hasn't been supported for over 3½ years... + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +31,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,38 +43,46 @@ 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. + * Deprecated and not supported after release `0.9.0`. + * Request records of all transactions against the given contract in the last 25 hours. */ message ContractGetRecordsQuery { option deprecated = true; /** - * 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 information sent with every query operation.
+ * This includes 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 + * A smart contract ID. + *

+ * The network SHALL return information for this smart contract, if successful. */ ContractID contractID = 2; } /** - * Before v0.9.0, returned records of all transactions against the given contract in the last 25 hours. + * Deprecated and not supported after release `0.9.0`. + * Response with records of all transactions against the given contract in the last 25 hours. */ message ContractGetRecordsResponse { option deprecated = true; /** - * Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * The smart contract instance that this record is for + * A smart contract that this response describes. */ ContractID contractID = 2; /** - * List of records, each with contractCreateResult or contractCallResult as its body + * A list of records, each with contractCreateResult or contractCallResult as its body */ repeated TransactionRecord records = 3; } diff --git a/sdk/src/main/proto/contract_types.proto b/sdk/src/main/proto/contract_types.proto index 5df7877bb..1e5d61678 100644 --- a/sdk/src/main/proto/contract_types.proto +++ b/sdk/src/main/proto/contract_types.proto @@ -1,13 +1,21 @@ +/** + * # Contract Message Types + * Message types used in contract transactions. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,21 +34,215 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; import "basic_types.proto"; - import "google/protobuf/wrappers.proto"; + /** - * Info about a contract account's nonce value. - * A nonce of a contract is only incremented when that contract creates another contract. + * A contract "nonce" reference.
+ * This connects a contract and its "nonce" value, and is primarily for use in + * query responses. A "nonce" is short for "nonsense" and is usually a value + * with no particular meaning. + * + * The nonce of a contract SHALL be incremented when that contract creates + * another contract. */ message ContractNonceInfo { + /** + * A contract identifier.
+ * This refers to the contract that holds this nonce value. + */ + ContractID contract_id = 1; + + /** + * A "nonce" value. + * The current value of the nonce associated with the identified contract. + */ + int64 nonce = 2; +} + +/** + * EVM log data for a contract call.
+ * The EVM log information produced by a smart contract function call. + * + * Each contract function call MAY return zero or more log events. + */ +message ContractLoginfo { + /** + * A contract identifier.
+ * This refers to the contract that generated this log entry. + */ + ContractID contractID = 1; + + /** + * A bloom filter.
+ * This filter applies to this log entry and indexes the contract log data + * in the full data of the Ethereum block.
+ * EIP-7668 proposes to remove bloom filters as they are quite low value + * in practice and separate indexing services are more effective. + */ + bytes bloom = 2; + + /** + * A list of the "topics" in this log entry.
+ * The EVM permits up to 4 topics, each of which is 32 bytes (one EVM word). + *

+ * The first "topic" is special, and MUST contain the keccak256 hash of the + * event signature, if the event is not anonymous. + */ + repeated bytes topic = 3; + + /** + * Event data for this log entry.
+ * This is binary data consisting of an arbitrary number of 256 bit + * (32 byte) words. The content of that data is determined by the smart + * contract code.
+ */ + bytes data = 4; +} + +/** + * A contract function result.
+ * 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. The ContractCreateInstance transaction record also carries a + * function result, which is the results of the call to the constructor. + */ +message ContractFunctionResult { + // No comments here: PBJ issue #217 + reserved 8; // Removed Field. + + /** + * A contract identifier.
+ * This identifies the smart contract that defines the function called. + */ + ContractID contractID = 1; + + /** + * Result data from the function call. + *

+ * This SHALL be encoded in RLP bytecode format. + */ + bytes contractCallResult = 2; + + /** + * Any error message produced by the contract call. + *

+ * This SHALL be unset if the contract call succeeded. + */ + string errorMessage = 3; + + /** + * A bloom filter produced by this contract call.
+ * Ethereum uses this bloom filter to search for call results in the + * Ethereum block history. High false positive rates make the bloom + * filters quite limited value. + */ + bytes bloom = 4; + + /** + * A quantity of "gas" used.
+ * This represents the resource units expended to execute this + * contract call, and correlates to transaction costs. + */ + uint64 gasUsed = 5; + + /** + * Any Log events produced by this contract call. + */ + repeated ContractLoginfo logInfo = 6; + + /** + * Replaced by values in transaction records to support + * `CREATE2` calls.
+ *

+ * The list of smart contracts that were created by the function call.
+ * The created ids will now _also_ be externalized through internal + * transaction records, where each record has its alias field populated + * with the new contract's EVM address.
+ * This is needed for contracts created with CREATE2, which removes the + * trivial relationship between a new contract's Identifier and its + * Solidity address. + */ + repeated ContractID createdContractIDs = 7 [deprecated = true]; + + /** + * A created contract address.
+ * If the function created a new contract (e.g. `CREATE2`), + * this is the primary 20-byte EVM address for that contract. + *

+ * Every contract SHALL have a "base" EVM address that is determined by its + * `shard.realm.num` contract ID.
+ * This address is constructed as follows + *

    + *
  1. The first 4 bytes are the big-endian + * representation of the shard.
    2. + *
  2. The next 8 bytes are the big-endian + * representation of the realm.
    3. + *
  3. The final 8 bytes are the big-endian + * representation of the number.
    4. + *
+ *

+ * Contracts created via `CREATE2` SHALL have an _additional_, primary, + * address that is derived from the + * EIP-1014 + * specification. This additional address SHALL NOT be directly related to + * the `shard.realm.num` contract ID.
+ * It should be emphasized that Contracts created via a `CREATE2` call can + * also be referenced via the same "base" EVM address as described above. + */ + google.protobuf.BytesValue evm_address = 9; + + /** + * The amount of gas available for this call, sometimes referred to as the + * gasLimit.
+ * This field SHALL NOT be populated when the associated `TransactionBody` + * in the block stream is a `ContractCreateTransactionBody` or + * a `ContractCallTransactionBody`. + */ + int64 gas = 10; + + /** + * An amount, in tinybar, sent by this function call.
+ * This SHALL be zero(0) if the function called is not `payable`.
+ * This field SHALL NOT be populated when the associated `TransactionBody` + * in the block stream is a `ContractCreateTransactionBody` or + * a `ContractCallTransactionBody`. + */ + int64 amount = 11; + + /** + * The smart contract function to call, and the parameters to pass to that + * function.
+ * These SHALL be presented in EVM bytecode function call format.
+ * This field SHALL NOT be populated when the associated `TransactionBody` + * in the block stream is a `ContractCreateTransactionBody` or + * a `ContractCallTransactionBody`. + */ + bytes functionParameters = 12; + + /** + * The account that was the "sender" for this contract call.
+ * If this is not set it SHALL be read from the accountId in the + * transactionId for the contract call.
+ * This field SHALL NOT be populated when the associated `TransactionBody` + * in the block stream is a `ContractCreateTransactionBody` or + * a `ContractCallTransactionBody`. + */ + AccountID sender_id = 13; - /** - * Id of the contract - */ - ContractID contract_id = 1; + /** + * A list of contract account nonce values.
+ * This list SHALL contain a nonce value for each contract account modified + * as a result of this contract call. These nonce values SHALL be the value + * after the contract call is completed. + */ + repeated ContractNonceInfo contract_nonces = 14; - /** - * The current value of the contract account's nonce property - */ - int64 nonce = 2; + /** + * A nonce value for the "signer account".
+ * If the contract call updated the signer nonce for the signer account + * (i.e. by creating another contract), this field SHALL contain the + * updated value.
+ * If the signer account nonce was not updated, this field SHALL be `null`. + */ + google.protobuf.Int64Value signer_nonce = 15; } diff --git a/sdk/src/main/proto/contract_update.proto b/sdk/src/main/proto/contract_update.proto index 976b2dfe7..c55ce7c8f 100644 --- a/sdk/src/main/proto/contract_update.proto +++ b/sdk/src/main/proto/contract_update.proto @@ -1,13 +1,23 @@ +/** + * # Contract Update + * Modify a smart contract. Any change other than updating the expiration time + * requires that the contract be modifiable (has a valid `adminKey`) and that + * the transaction be signed by the `adminKey` + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +29,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,75 +41,95 @@ import "timestamp.proto"; import "google/protobuf/wrappers.proto"; /** - * At consensus, updates the fields of a smart contract to the given values. + * Modify the current state of a smart contract. * - * 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. + * ### Requirements + * - The `adminKey` MUST sign all contract update transactions except one + * that only updates the `expirationTime`. + * - A transaction that modifies any field other than `expirationTime` for + * a contract without a valid `adminKey` set SHALL fail with response + * code `MODIFYING_IMMUTABLE_CONTRACT`. + * - Fields set to non-default values in this transaction SHALL be updated on + * success. Fields not set to non-default values SHALL NOT be + * updated on success. * - * --- 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.) - * 4. If the update transaction sets the AccountID auto_renew_account_id wrapper field to anything - * other than the sentinel 0.0.0 value, then the key of the referenced account must sign. + * ### Block Stream Effects + * None */ message ContractUpdateTransactionBody { /** - * The id of the contract to be updated + * The contact ID that identifies the smart contract to be updated.
+ * This field MUST be set, and MUST NOT be a default ID (`0.0.0`). */ ContractID contractID = 1; /** - * The new expiry of the contract, no earlier than the current expiry (resolves to - * EXPIRATION_REDUCTION_NOT_ALLOWED otherwise) + * If set, modify the time at which this contract will expire.
+ * An expired contract requires a rent payment to "renew" the contract. + * A transaction to update this field is how that rent payment is made. + *

+ * This value MUST NOT be less than the current `expirationTime` + * of the contract. If this value is earlier than the current + * value, the transaction SHALL fail with response + * code `EXPIRATION_REDUCTION_NOT_ALLOWED`. */ Timestamp expirationTime = 2; /** - * The new key to control updates to the contract + * If set, modify the key that authorizes updates to the contract. + *

+ * If this field is set to a valid Key, this key and the previously set key + * MUST both sign this transaction.
+ * If this value is an empty `KeyList`, the prior key MUST sign this + * transaction, and the smart contract SHALL be immutable after this + * transaction completes, except for expiration and renewal.
+ * If this value is not an empty `KeyList`, but does not contain any + * cryptographic keys, or is otherwise malformed, this transaction SHALL + * fail with response code `INVALID_ADMIN_KEY`. */ Key adminKey = 3; /** - * [Deprecated] The new id of the account to which the contract is proxy staked + * Replaced with `staked_id` alternatives. + * This field is unused and SHALL NOT modify the contract state.
+ * The id of an account to which the contract is proxy staked */ AccountID proxyAccountID = 6 [deprecated = true]; /** - * If an auto-renew account is in use, the lifetime to be added by each auto-renewal. + * If set, modify the duration added to expiration time by each + * auto-renewal to this value. */ Duration autoRenewPeriod = 7; /** - * This field is unused and will have no impact on the specified smart contract. + * This field is unused and SHALL NOT modify the contract state.
+ * Previously, an ID of a file containing the bytecode of the Solidity + * transaction that created this contract. */ FileID fileID = 8 [deprecated = true]; - /** - * The new contract memo, assumed to be Unicode encoded with UTF-8 (at most 100 bytes) - */ + // This should be condensed to just a field instead of a oneof and field 9 reserved. oneof memoField { - /** - * [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; + /** + * This value could not accurately distinguish unset or deliberately + * empty. memoWrapper should be used instead.
+ */ + string memo = 9 [deprecated = true]; + + /** + * If set, modify the short memo for this smart contract. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. + */ + google.protobuf.StringValue memoWrapper = 10; } /** * If set, modify the maximum number of tokens that can be auto-associated with the - * contract.
+ * contract. + *

* If this is set and less than or equal to `used_auto_associations`, or 0, then this contract * MUST manually associate with a token before transacting in that token.
* This value MAY also be `-1` to indicate no limit.
@@ -109,31 +138,59 @@ message ContractUpdateTransactionBody { google.protobuf.Int32Value max_automatic_token_associations = 11; /** - * If set to the sentinel 0.0.0 AccountID, this field removes the contract's auto-renew - * account. Otherwise it updates the contract's auto-renew account to the referenced account. + * If set, modify the account, in the same shard and realm as this smart + * contract, that has agreed to allow the network to use its balance, when + * needed, to automatically extend this contract's expiration time. + *

+ * If this field is set to a non-default value, that Account MUST sign this + * transaction.
+ * If this field is set to a default AccountID value (`0.0.0`), any + * pre-existing `auto_renew_account_id` value SHALL be removed on success. */ AccountID auto_renew_account_id = 12; - /** - * ID of the new account or node to which this contract is staking. - */ oneof staked_id { - /** - * ID of the new account to which this contract is staking. If set to the sentinel 0.0.0 AccountID, - * this field removes the contract's staked account ID. + * An account identifier.
+ * A staked account acts as a proxy, and this contract effectively + * nominates the same node as the identified account. + *

+ * If set, modify this smart contract such that it SHALL stake its HBAR + * to the same node as the identified account.
+ * If this field is set to a default AccountID value (`0.0.0`), any + * pre-existing `staked_account_id` value SHALL be removed on success. */ AccountID staked_account_id = 13; /** - * ID of the new node this contract is staked to. If set to the sentinel -1, this field - * removes the contract's staked node ID. + * A node identifier.
+ * A staked node identifier indicates the consensus node that this + * account nominates for staking. + *

+ * If set, modify this smart contract such that it SHALL stake its HBAR + * to this node. + * If set to a the value `-1` any pre-existing `staked_node_id` value + * SHALL be removed on success. + *

+ *

Note: node IDs do fluctuate as node operators change. + * Most contracts are immutable, and a contract staking to an invalid + * node ID SHALL NOT participate in staking. Immutable contracts may + * find it more reliable to use a proxy account for staking (via + * `staked_account_id`) to enable updating the _effective_ staking node + * ID when necessary through updating the proxy account.
*/ int64 staked_node_id = 14; } /** - * If true, the contract declines receiving a staking reward. + * A flag indicating if staking rewards are declined.
+ * If set, modify the flag indicating if this contract declines to accept + * rewards for staking its HBAR to secure the network. + *

+ * If set to true, this smart contract SHALL NOT receive any reward for + * staking its HBAR balance to help secure the network, regardless of + * staking configuration, but MAY stake HBAR to support the network + * without reward. */ google.protobuf.BoolValue decline_reward = 15; } diff --git a/sdk/src/main/proto/crypto_add_live_hash.proto b/sdk/src/main/proto/crypto_add_live_hash.proto index 467009b96..e7a518de5 100644 --- a/sdk/src/main/proto/crypto_add_live_hash.proto +++ b/sdk/src/main/proto/crypto_add_live_hash.proto @@ -1,13 +1,26 @@ +/** + * # Add Live Hash + * Associate content to an account via a SHA-384 hash. + * + * > Important + * >> This transaction is obsolete and not supported.
+ * >> Any transaction of this type that is submitted SHALL fail + * >> with a `PRE_CHECK` result of `NOT_SUPPORTED`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +32,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,45 +43,59 @@ 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 Live Hash value associating some item of content to an account. + * + * This message represents a desired entry in the ledger for a SHA-384 + * hash of some content, an associated specific account, a list of authorized + * keys, and a duration the live hash is "valid". */ message LiveHash { /** - * The account to which the livehash is attached + * An account associated via this live hash to the hashed content. */ AccountID accountId = 1; /** - * The SHA-384 hash of a credential or certificate + * A SHA-384 hash of some content that is associated to the account + * or account holder. */ 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, all of which MUST sign the transaction to add the + * live hash.
+ * Any one of these keys may, however, remove the live hash to revoke + * the association. */ KeyList keys = 3; /** - * The duration for which the livehash will remain valid + * A duration describing how long this Live Hash SHALL remain valid.
+ * A Live Hash SHOULD NOT be relied upon after this duration has elapsed. */ 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. + * Add a hash value to the ledger and associate it with an account. + * + * Create an entry in the ledger for a SHA-384 hash of some content, and + * associate that with a specific account. This is sometimes used to associate + * a credential or certificate with an account as a public record.
+ * The entry created is also associated with a list of keys, all of which + * MUST sign this transaction.
+ * The account key for the associated account MUST sign this transaction.
+ * + * The live hash, once created, MAY be removed from the ledger with one + * or more signatures. + * - The account key of the account associated to the live hash. + * - Any one key from the key list in the live hash entry. + * - Any combination of keys from the key list in the live hash entry. */ message CryptoAddLiveHashTransactionBody { /** - * A hash of some credential or certificate, along with the keys of the entities that asserted it validity + * A Live Hash to be added to the ledger and associated with + * the identified account. */ LiveHash liveHash = 3; } diff --git a/sdk/src/main/proto/crypto_approve_allowance.proto b/sdk/src/main/proto/crypto_approve_allowance.proto index 40a3d7142..1c17f5d37 100644 --- a/sdk/src/main/proto/crypto_approve_allowance.proto +++ b/sdk/src/main/proto/crypto_approve_allowance.proto @@ -1,13 +1,25 @@ +/** + * # Approve Allowance + * This transaction body provides a mechanism to add "allowance" entries + * for an account. These allowances enable one account to spend or transfer + * token balances (for fungible/common tokens), individual tokens (for + * non-fungible/unique tokens), or all non-fungible tokens owned by the + * account, now or in the future (if `approved_for_all` is set). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2022 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +31,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -30,111 +41,218 @@ import "basic_types.proto"; import "google/protobuf/wrappers.proto"; /** - * Creates one or more hbar/token approved allowances relative to the owner account specified in the allowances of - * this transaction. Each allowance grants a spender the right to transfer a pre-determined amount of the owner's - * hbar/token to any other account of the spender's choice. If the owner is not specified in any allowance, the payer - * of transaction is considered to be the owner for that particular allowance. - * Setting the amount to zero in CryptoAllowance or TokenAllowance will remove the respective allowance for the spender. + * Create ("Approve") allowances for one account to transfer tokens owned + * by a different account.
+ * An allowance permits a "spender" account to independently transfer tokens + * owned by a separate "owner" account. Each such allowance permits spending + * any amount, up to a specified limit, for fungible/common tokens; a single + * specified non-fungible/unique token, or all non-fungible/unique tokens + * of a particular token type held by the "owner" account. + * + * If the "owner" account is not specified for any allowance in this + * transaction (the `owner` field is not set), the `payer` account for this + * transaction SHALL be owner for that allowance.
+ * Each `owner` account specified in any allowance approved in this + * transaction MUST sign this transaction.
+ * If the `amount` field for any fungible/common allowance in this + * transaction is `0`, then that allowance SHOULD match an existing, + * previously approved, allowance which SHALL be removed.
+ * There are three lists in this message. Each list MAY be empty, but + * _at least one_ list MUST contain _at least one_ entry. + * + * Example for the `payer` rule.
+ * - Given an account `0.0.X` that pays for this transaction, and owner + * is not specified in an allowance of `200` HBAR to spender account + * `0.0.Y`. At consensus the spender account `0.0.Y` will have a new + * allowance to spend `200` HBAR from the balance of account `0.0.X`. * - * (So if account 0.0.X pays for this transaction and owner is not specified in the allowance, - * then at consensus each spender account will have new allowances to spend hbar or tokens from 0.0.X). + * ### Block Stream Effects + * None */ message CryptoApproveAllowanceTransactionBody { - /** - * List of hbar allowances approved by the account owner. - */ - repeated CryptoAllowance cryptoAllowances = 1; - - /** - * List of non-fungible token allowances approved by the account owner. - */ - repeated NftAllowance nftAllowances = 2; - - /** - * List of fungible token allowances approved by the account owner. - */ - repeated TokenAllowance tokenAllowances = 3; + /** + * List of hbar allowances approved by the account owner. + *

+ * This list MAY be empty, provided at least one other list is + * not empty. + */ + repeated CryptoAllowance cryptoAllowances = 1; + + /** + * List of non-fungible token allowances approved by the account owner. + *

+ * This list MAY be empty, provided at least one other list is + * not empty. + */ + repeated NftAllowance nftAllowances = 2; + + /** + * List of fungible token allowances approved by the account owner. + *

+ * This list MAY be empty, provided at least one other list is + * not empty. + */ + repeated TokenAllowance tokenAllowances = 3; } /** - * An approved allowance of hbar transfers for a spender. + * An approved allowance of hbar transfers. + * This message specifies one allowance for a single, unique, combination + * of owner, spender, and amount. + * + * If `owner` is not set, the effective `owner` SHALL be the `payer` for the + * enclosing transaction.
+ * The `spender` MUST be specified and MUST be a valid account.
+ * The `amount` MUST be a whole number, and SHOULD be greater than `0` unless + * this allowance is intended to _remove_ a previously approved allowance. */ message CryptoAllowance { - /** - * The account ID of the hbar owner (ie. the grantor of the allowance). - */ - AccountID owner = 1; - - /** - * The account ID of the spender of the hbar allowance. - */ - AccountID spender = 2; - - /** - * The amount of the spender's allowance in tinybars. - */ - int64 amount = 3; + /** + * An owner account identifier.
+ * This is the account identifier of the account granting an allowance + * for the `spender` to transfer tokens held by this account. + */ + AccountID owner = 1; + + /** + * A spender account identifier.
+ * This is the account identifier of the account permitted to transfer + * tokens held by the `owner`. + */ + AccountID spender = 2; + + /** + * An amount of tinybar (10-8 HBAR).
+ * This is the amount of HBAR held by the `owner` that the + * `spender` is permitted to transfer. + *

+ * This value MUST be a whole number.
+ * This value MUST be greater than 0 to create a new allowance.
+ * This value MAY be exactly `0` to _remove_ an existing allowance.
+ */ + int64 amount = 3; } /** - * An approved allowance of non-fungible token transfers for a spender. + * An approved allowance of non-fungible tokens.
+ * This type of allowance may permit transfers for one or more individual + * unique tokens, or may permit transfers for all unique tokens of the + * specified type. + * + * If `owner` is not set, the effective `owner` SHALL be the `payer` for the + * enclosing transaction.
+ * The `spender` MUST be specified and MUST be a valid account.
+ * If `approve_for_all` is set, then `serial_numbers` SHOULD be empty + * and SHALL be ignored. + * If `approve_for_all` is unset, then `serial_numbers` MUST NOT be empty. */ message NftAllowance { - /** - * The NFT token type that the allowance pertains to. - */ - TokenID tokenId = 1; - - /** - * The account ID of the token owner (ie. the grantor of the allowance). - */ - AccountID owner = 2; - - /** - * The account ID of the token allowance spender. - */ - AccountID spender = 3; - - /** - * The list of serial numbers that the spender is permitted to transfer. - */ - repeated int64 serial_numbers = 4; - - /** - * If true, the spender has access to all of the owner's NFT units of type tokenId (currently - * owned and any in the future). - */ - google.protobuf.BoolValue approved_for_all = 5; - - /** - * The account ID of the spender who is granted approvedForAll allowance and granting - * approval on an NFT serial to another spender. - */ - AccountID delegating_spender = 6; + /** + * A token identifier.
+ * This identifies the type of token the `spender` is permitted to + * transfer from the `owner`. + *

+ * The identified token type MUST be a non-fungible/unique token. + */ + TokenID tokenId = 1; + + /** + * An owner account identifier.
+ * This is the account identifier of the account granting an allowance + * for the `spender` to transfer tokens held by this account. + */ + AccountID owner = 2; + + /** + * A spender account identifier.
+ * This is the account identifier of the account permitted to transfer + * tokens held by the `owner`. + */ + AccountID spender = 3; + + /** + * A list of token serial numbers.
+ * The list of serial numbers that the spender is permitted to transfer. + *

+ * The `owner` MUST currently hold each token identified in this list. + */ + repeated int64 serial_numbers = 4; + + /** + * A flag indicating this allowance applies to all tokens of the + * specified (non-fungible/unique) type. + *

+ * If true, the `spender` SHALL be permitted to transfer any or all + * of the `owner`'s tokens of the specified token type. + * This SHALL apply not only to currently owned tokens, but to all + * such tokens acquired in the future, unless the + * allowance is `delete`d. + */ + google.protobuf.BoolValue approved_for_all = 5; + + /** + * A spender-owner account identifier.
+ * This account identifier identifies a `spender` for whom an existing + * `approved_for_all` allowance was previously created. This enables + * an account with such broad access to grant allowances to transfer + * individual tokens from the original owner without involving that + * original owner. + *

+ * If this is set, the account identified MUST sign this transaction, but + * the `owner` account MAY NOT sign this transaction.
+ * If this is set, there MUST exist an active `approved_for_all` + * allowance from the `owner` for the `delegating_spender` to transfer + * all tokens of the type identified by the `tokenId` field.
+ * If this value is set, the `approved_for_all` flag MUST be `false`. + */ + AccountID delegating_spender = 6; } /** - * An approved allowance of fungible token transfers for a spender. + * An approved allowance of fungible/common token transfers. + * This message specifies one allowance for a single, unique, combination + * of token, owner, spender, and amount. + * + * If `owner` is not set, the effective `owner` SHALL be the `payer` for the + * enclosing transaction.
+ * The `tokenId` MUST be specified and MUST be a valid + * fungible/common token type.
+ * The `spender` MUST be specified and MUST be a valid account.
+ * The `amount` MUST be a whole number, and SHOULD be greater than `0` unless + * this allowance is intended to _remove_ a previously approved allowance. */ message TokenAllowance { - /** - * The token that the allowance pertains to. - */ - TokenID tokenId = 1; - - /** - * The account ID of the token owner (ie. the grantor of the allowance). - */ - AccountID owner = 2; - - /** - * The account ID of the token allowance spender. - */ - AccountID spender = 3; - - /** - * The amount of the spender's token allowance. - */ - int64 amount = 4; -} + /** + * A token identifier.
+ * This identifies the type of token the `spender` is permitted to + * transfer from the `owner`. + *

+ * The identified token type MUST be a fungible/common token. + */ + TokenID tokenId = 1; + + /** + * An owner account identifier.
+ * This is the account identifier of the account granting an allowance + * for the `spender` to transfer tokens held by this account. + */ + AccountID owner = 2; + /** + * A spender account identifier.
+ * This is the account identifier of the account permitted to transfer + * tokens held by the `owner`. + */ + AccountID spender = 3; + + /** + * An amount of fractional tokens (10-decimals tokens).
+ * This is the amount of tokens held by the `owner` that the + * `spender` is permitted to transfer. + *

+ * This value MUST be a whole number.
+ * This value MUST be greater than 0 to create a new allowance.
+ * This value MAY be exactly `0` to _remove_ an existing allowance.
+ */ + int64 amount = 4; +} diff --git a/sdk/src/main/proto/crypto_create.proto b/sdk/src/main/proto/crypto_create.proto index 0d4740a09..8dd13e0af 100644 --- a/sdk/src/main/proto/crypto_create.proto +++ b/sdk/src/main/proto/crypto_create.proto @@ -1,13 +1,21 @@ +/** + * # Crypto Create + * Messages to create a new end-user account within the distributed ledger. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -30,147 +37,180 @@ 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. If the - * auto_renew_account field is set, the key of the referenced account must sign. + * Create a new 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. + * If the auto_renew_account field is set, the key of the referenced account + * MUST sign this transaction.
+ * Current limitations REQUIRE that `shardID` and `realmID` both MUST be `0`. + * This is expected to change in the future. * - * 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. + * ### Block Stream Effects + * The newly created account SHALL be included in State Changes. */ message CryptoCreateTransactionBody { + // Removed prior to oldest available history + reserved 4,5; + /** - * 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. + * The identifying key for this account. + * This key represents the account owner, and is required for most actions + * involving this account that do not modify the account itself. This key + * may also identify the account for smart contracts. + *

+ * This field is REQUIRED. + * This `Key` MUST NOT be an empty `KeyList` and MUST contain at least one + * "primitive" (i.e. cryptographic) key value. */ Key key = 1; /** - * The initial number of tinybars to put into the account + * An amount, in tinybar, to deposit to the newly created account. + *

+ * The deposited amount SHALL be debited to the "payer" account for this + * transaction. */ uint64 initialBalance = 2; /** - * [Deprecated] 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. + * Use `staked_id` instead.
+ * An account identifier for a staking proxy. */ AccountID proxyAccountID = 3 [deprecated = true]; /** - * [Deprecated]. The threshold amount (in tinybars) for which an account record is created for - * any send/withdraw transaction + * Removed prior to the first available history, and may be related to an + * early design dead-end.
+ * An amount below which record stream records would not be created for + * a transaction that reduces this account balance. */ - uint64 sendRecordThreshold = 6 [deprecated=true]; + uint64 sendRecordThreshold = 6 [deprecated = true]; /** - * [Deprecated]. The threshold amount (in tinybars) for which an account record is created for - * any receive/deposit transaction + * Removed prior to the first available history, and may be related to an + * early design dead-end.
+ * An amount below which record stream records would not be created for + * a transaction that increases this account balance. */ - uint64 receiveRecordThreshold = 7 [deprecated=true]; + uint64 receiveRecordThreshold = 7 [deprecated = true]; /** - * If true, this account's key must sign any transaction depositing into this account (in - * addition to all withdrawals) + * A flag indicating the account holder must authorize all incoming + * token transfers. + *

+ * If this flag is set then any transaction that would result in adding + * hbar or other tokens to this account balance MUST be signed by the + * identifying key of this account (that is, the `key` field).
+ * If this flag is set, then the account key (`key` field) MUST sign + * this create transaction, in addition to the transaction payer. */ 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. + * The duration between account automatic renewals.
+ * All entities in state may be charged "rent" occasionally (typically + * every 90 days) to prevent unnecessary growth of the ledger. This value + * sets the interval between such events for this account. + *

+ * If the account balance (in HBAR) is insufficient to pay the full renewal + * fee, the entire HBAR balance SHALL be consumed and the expiration for + * the account SHALL be extended as far as the available balance can + * support.
+ * If the account HBAR balance is `0` when the account must be renewed, then + * the account SHALL be deleted, and subsequently removed from state. */ Duration autoRenewPeriod = 9; /** * The shard in which this account is created + *

+ * Currently, this MUST be `0`.
+ * If the desired shard is `0`, this SHOULD NOT be set. */ ShardID shardID = 10; /** - * The realm in which this account is created (leave this null to create a new realm) + * The realm in which this account is created. + *

+ * The shard number for this realm MUST match the value in `shardID`.
+ * Currently, this MUST be `0` for both fields.
+ * If the desired realm is `0`, this SHOULD NOT be set. */ RealmID realmID = 11; /** - * If realmID is null, then this the admin key for the new realm that will be created + * This field was never actually used or enabled, and is not expected to + * ever be used in the future.
*/ - Key newRealmAdminKey = 12; + Key newRealmAdminKey = 12 [deprecated = true]; /** - * The memo associated with the account (UTF-8 encoding max 100 bytes) + * A short description of this Account. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 13; /** - * The maximum number of tokens that can be auto-associated with the account.
- * If this is less than or equal to `used_auto_associations`, or 0, then this account - * MUST manually associate with a token before transacting in that token.
+ * A maximum number of tokens that can be auto-associated + * with this account.
+ * By default this value is 0 for all accounts except for automatically + * created accounts (e.g. smart contracts), which default to -1. + *

+ * If this value is `0`, then this account MUST manually associate to + * a token before holding or transacting in that token.
* This value MAY also be `-1` to indicate no limit.
- * This value MUST NOT be less than `-1`.
- * By default this value is 0 for accounts except for auto-created accounts which default -1. + * This value MUST NOT be less than `-1`. */ int32 max_automatic_token_associations = 14; - /** - * ID of the account or node to which this account is staking. - */ oneof staked_id { - /** - * ID of the account to which this account is staking. + * ID of the account to which this account is staking its balances. + *

+ * If this account is not currently staking its balances, then this + * field, if set, MUST be the sentinel value of `0.0.0`. */ AccountID staked_account_id = 15; /** * ID of the node this account is staked to. + *

+ * If this account is not currently staking its balances, then this + * field, if set, SHALL be the sentinel value of `-1`.
+ * Wallet software SHOULD surface staking issues to users and provide a + * simple mechanism to update staking to a new node ID in the event the + * prior staked node ID ceases to be valid. */ int64 staked_node_id = 16; } /** - * If true, the account declines receiving a staking reward. The default value is false. + * A boolean indicating that this account has chosen to decline rewards for + * staking its balances. + *

+ * This account MAY still stake its balances, but SHALL NOT receive reward + * payments for doing so, if this value is set. */ bool decline_reward = 17; /** - * The bytes to be used as the account's alias. It will be the - * serialization of a protobuf Key message for an ED25519/ECDSA_SECP256K1 primitive key type. Currently only primitive key bytes are - * supported as the key for an account with an alias. ThresholdKey, KeyList, ContractID, and - * delegatable_contract_id are not supported. - * - * May also be the EOA 20-byte address to create that is derived from the keccak-256 hash of a ECDSA_SECP256K1 primitive key. - * - * A given alias can map to at most one account on the network at a time. This uniqueness will be enforced - * relative to aliases currently on the network at alias assignment. - * - * If a transaction creates an account using an alias, any further crypto transfers to that alias will - * simply be deposited in that account, without creating anything, and with no creation fee being charged. + * Bytes to be used as the account's alias. + *

+ * This value, if set, MUST be one of the following values
+ *

    + *
  • The 32-byte serialized form of the ED25519 account key.
    • + *
  • The 33-byte _compressed_ serialized form of the ECDSA(secp256k1) + * account key.
    • + *
  • The 20-byte EVM address derived from a keccak-256 hash of the + * ECDSA(secp256k1) account key
    • + *
+ * All aliases within the network MUST be unique. If this value matches an + * existing account alias, this `create` transaction SHALL fail.
+ * If an account exists with a particular alias value, any transaction to + * transfer value _to_ that alias SHALL deposit the transferred value in + * the existing account, and SHALL NOT assess an account creation fee.
+ * Once set, an account alias is immutable and MUST NOT be changed. */ - bytes alias = 18; + bytes alias = 18; } diff --git a/sdk/src/main/proto/crypto_delete.proto b/sdk/src/main/proto/crypto_delete.proto index 30719afe4..696fd065b 100644 --- a/sdk/src/main/proto/crypto_delete.proto +++ b/sdk/src/main/proto/crypto_delete.proto @@ -1,13 +1,21 @@ +/** + * # Crypto Delete + * Message to delete an account. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,18 +36,43 @@ 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. + * Delete an account.
+ * This will mark an account deleted, and transfer all tokens to a "sweep" + * account. + * + * A deleted account SHALL NOT hold a balance in any token type.
+ * A deleted account SHALL remain in state until it expires.
+ * Transfers that would increase the balance of a deleted account + * SHALL fail.
+ * A deleted account MAY be subject of a `cryptoUpdate` transaction to extend + * its expiration.
+ * When a deleted account expires it SHALL be removed entirely, and SHALL NOT + * be archived. + * + * ### Block Stream Effects + * None */ message CryptoDeleteTransactionBody { /** - * The account ID which will receive all remaining hbars + * An account identifier. + *

+ * The identified account SHALL receive all tokens, token balances, + * and non-fungible/unique from the deleted account.
+ * The identified account MUST sign this transaction.
+ * If not set, the account to be deleted MUST NOT have a balance in any + * token, a balance in HBAR, or hold any NFT. */ AccountID transferAccountID = 1; /** - * The account ID which should be deleted + * An account identifier. + *

+ * This account SHALL be deleted if this transaction succeeds.
+ * This account SHOULD NOT hold any balance other than HBAR.
+ * If this account _does_ hold balances, the `transferAccountID` value + * MUST be set to a valid transfer account.
+ * This account MUST sign this transaction.
+ * This field MUST be set to a valid account identifier. */ AccountID deleteAccountID = 2; } diff --git a/sdk/src/main/proto/crypto_delete_allowance.proto b/sdk/src/main/proto/crypto_delete_allowance.proto index 475df5f86..c3fa49bd6 100644 --- a/sdk/src/main/proto/crypto_delete_allowance.proto +++ b/sdk/src/main/proto/crypto_delete_allowance.proto @@ -1,13 +1,22 @@ +/** + * # Crypto Delete Allowance + * Delete one or more NFT allowances that permit transfer of tokens from + * an "owner" account by a different, "spender", account. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2022 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,34 +37,72 @@ option java_multiple_files = true; import "basic_types.proto"; /** - * Deletes one or more non-fungible approved allowances from an owner's account. This operation - * will remove the allowances granted to one or more specific non-fungible token serial numbers. Each owner account - * listed as wiping an allowance must sign the transaction. Hbar and fungible token allowances - * can be removed by setting the amount to zero in CryptoApproveAllowance. + * Delete one or more allowances.
+ * Given one or more, previously approved, allowances for non-fungible/unique + * tokens to be transferred by a spending account from an owning account; + * this transaction removes a specified set of those allowances. + * + * The owner account for each listed allowance MUST sign this transaction.
+ * Allowances for HBAR cannot be removed with this transaction. The owner + * account MUST submit a new `cryptoApproveAllowance` transaction with the + * amount set to `0` to "remove" that allowance.
+ * Allowances for fungible/common tokens cannot be removed with this + * transaction. The owner account MUST submit a new `cryptoApproveAllowance` + * transaction with the amount set to `0` to "remove" that allowance.
+ * + * ### Block Stream Effects + * None */ message CryptoDeleteAllowanceTransactionBody { /** - * List of non-fungible token allowances to remove. + * List of non-fungible/unique token allowances to remove. + *

+ * This list MUST NOT be empty. */ repeated NftRemoveAllowance nftAllowances = 2; + + // Note: Field numbers 1 and 3 were very briefly used in early + // versions of this file, but were removed prior to any release + // version. Those field numbers MAY be reused. } /** - * Nft allowances to be removed on an owner account + * A single allowance for one non-fungible/unique token. + * This is specific to removal, and the allowance is identified for that + * specific purpose. + * + * All fields in this message are REQUIRED. + * The `serial_numbers` list MUST NOT be empty. + * The combination of field values in this message MUST match existing + * allowances for one or more individual non-fungible/unique tokens. + * + * ### Removing an allowance that is `approve_for_all` + * To remove an allowance that has set the `approve_for_all` flag, the + * `owner` account must first _approve_ a **new** allowance for a specific + * serial number using a `cryptoApproveAllowance`, and then, if desired, + * that newly approved allowance to a specific serial number may be + * deleted in a separate `cryptoDeleteAllowance` transaction. */ message NftRemoveAllowance { /** - * The token that the allowance pertains to. + * A token identifier. + *

+ * This MUST be a valid token identifier for a non-fungible/unique + * token type. */ TokenID token_id = 1; /** - * The account ID of the token owner (ie. the grantor of the allowance). + * An `owner` account identifier. + *

+ * This account MUST sign the transaction containing this message. */ AccountID owner = 2; /** * The list of serial numbers to remove allowances from. + *

+ * This list MUST NOT be empty. */ repeated int64 serial_numbers = 3; } diff --git a/sdk/src/main/proto/crypto_delete_live_hash.proto b/sdk/src/main/proto/crypto_delete_live_hash.proto index 41ba5dfbc..d2dc9752e 100644 --- a/sdk/src/main/proto/crypto_delete_live_hash.proto +++ b/sdk/src/main/proto/crypto_delete_live_hash.proto @@ -1,13 +1,26 @@ +/** + * # Delete Live Hash + * Dissociate a specific live hash from a specified account. + * + * > Important + * >> This transaction is obsolete and not supported.
+ * >> Any transaction of this type that is submitted SHALL fail with a `PRE_CHECK` result + * >> of `NOT_SUPPORTED`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +32,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,17 +41,22 @@ 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. + * Delete a specific live hash associated to a given account. + * + * This transaction MUST be signed by either the key of the associated account, + * or at least one of the keys listed in the live hash. + * + * ### Block Stream Effects + * None */ message CryptoDeleteLiveHashTransactionBody { /** - * The account owning the livehash + * An account associated to a live hash. */ AccountID accountOfLiveHash = 1; /** - * The SHA-384 livehash to delete from the account + * The SHA-384 value of a specific live hash to delete. */ bytes liveHashToDelete = 2; } diff --git a/sdk/src/main/proto/crypto_get_account_balance.proto b/sdk/src/main/proto/crypto_get_account_balance.proto index 78b75d6be..3dc1c9353 100644 --- a/sdk/src/main/proto/crypto_get_account_balance.proto +++ b/sdk/src/main/proto/crypto_get_account_balance.proto @@ -1,13 +1,24 @@ +/** + * # Crypto Get Account Balance + * Query request to obtain balance information for a single account. + * + * This query SHOULD NOT be used by client software, queries to a + * Mirror Node provide more information at much lower cost. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +30,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,55 +41,81 @@ import "query_header.proto"; import "response_header.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. + * Query to read the HBAR balance of an account or contract. + * + * This query SHALL return _only_ the HBAR balance for an account + * or smart contract. Early releases of the network would return all + * fungible/common token balances, but HIP-367 made it infeasible to + * return all such balances. This query SHALL NOT return any information + * beyond the current HBAR balance. */ message CryptoGetAccountBalanceQuery { /** - * 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 information sent with every query operation.
+ * This includes the signed payment and what kind of response is requested + * (cost, state proof, both, or neither). */ QueryHeader header = 1; oneof balanceSource { - /** - * The account ID for which information is requested - */ - AccountID accountID = 2; + /** + * An account identifier.
+ * This identifies an account for which the balance is requested. + *

+ * Exactly one identifier MUST be provided. + */ + AccountID accountID = 2; - /** - * The account ID for which information is requested - */ - ContractID contractID = 3; + /** + * A smart contract identifier.
+ * This identifies a smart contract for which the balance is requested. + *

+ * Exactly one identifier MUST be provided. + */ + ContractID contractID = 3; } } /** - * Response when the client sends the node CryptoGetAccountBalanceQuery + * Response to a CryptoGetAccountBalanceQuery.
+ * + * This response SHALL contain only the information needed to + * identify the query request and the actual HBAR balance of the + * identified account or contract. */ message CryptoGetAccountBalanceResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither. + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, 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) + * An account identifier.
+ * This is the account ID queried.
+ * The inclusion of the account queried is useful with state proofs, + * when needed to prove an account balance to a third party. */ AccountID accountID = 2; /** - * The current balance, in tinybars. + * A current account balance.
+ * This is the current HBAR balance denominated in tinybar + * (10-8 HBAR). */ uint64 balance = 3; /** - * [DEPRECATED] The balances of the tokens associated to the account. This field was - * deprecated by HIP-367, which allowed - * an account to be associated to an unlimited number of tokens. This scale makes it more - * efficient for users to consult mirror nodes to review their token balances. + * This field became infeasible to support after HIP-367 removed limits on + * the number of associated tokens.
+ * A list of token balances for all tokens associated to the account. + *

+ * This field was deprecated by + * HIP-367, which + * allowed an account to be associated to an unlimited number of tokens. + * This scale makes it more efficient for users to consult mirror nodes + * to review their token balances. */ repeated TokenBalance tokenBalances = 4 [deprecated = true]; } diff --git a/sdk/src/main/proto/crypto_get_account_records.proto b/sdk/src/main/proto/crypto_get_account_records.proto index 183297249..dd4a99f91 100644 --- a/sdk/src/main/proto/crypto_get_account_records.proto +++ b/sdk/src/main/proto/crypto_get_account_records.proto @@ -1,13 +1,26 @@ +/** + * # Crypto Get Account Records + * Messages for a query to retrieve recent transaction records involving a + * specified account as effective `payer`.
+ * A "recent" transaction is typically one that reached consensus within + * the previous three(`3`) minutes of _consensus_ time. Additionally, the + * network only stores records in state when + * `ledger.keepRecordsInState=true` was true during transaction handling. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +32,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,38 +44,53 @@ 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. + * Request records of all "recent" transactions for which the specified + * account is the effective payer. */ message CryptoGetAccountRecordsQuery { /** - * 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 information sent with every query operation.
+ * This includes 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 + * An account identifier.
+ * This identifies the account to use when filtering the + * transaction record lists. + *

+ * This field is REQUIRED. */ 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. + * Return records of all "recent" transactions for which the specified + * account is the effective payer. */ message CryptoGetAccountRecordsResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * The account that this record is for + * An account identifier.
+ * This identifies the account used when filtering the + * transaction record lists. + *

+ * This field SHALL match the requested account identifier. */ AccountID accountID = 2; /** - * List of records + * A list of records. + *

+ * This list SHALL contain all available and "recent" records in which + * the account identified in the `accountID` field acted as effective payer. */ repeated TransactionRecord records = 3; } - - diff --git a/sdk/src/main/proto/crypto_get_info.proto b/sdk/src/main/proto/crypto_get_info.proto index 62e60a172..0bfdaf98f 100644 --- a/sdk/src/main/proto/crypto_get_info.proto +++ b/sdk/src/main/proto/crypto_get_info.proto @@ -1,13 +1,21 @@ +/** + * # Get Account Information + * A standard query to inspect the full detail of an account. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2022 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -34,13 +41,18 @@ 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. + * A query to read information for an account. + * + * The returned information SHALL include balance.
+ * The returned information SHALL NOT include allowances.
+ * The returned information SHALL NOT include token relationships.
+ * The returned information SHALL NOT include account records. */ message CryptoGetInfoQuery { /** - * 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 information sent with every query operation.
+ * This includes the signed payment and what kind of response is requested + * (cost, state proof, both, or neither). */ QueryHeader header = 1; @@ -55,119 +67,211 @@ message CryptoGetInfoQuery { */ message CryptoGetInfoResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; + /** + * Information describing A single Account in the Hedera distributed ledger. + * + * #### Attributes + * Each Account may have a unique three-part identifier, a Key, and one or + * more token balances. Accounts also have an alias, which has multiple + * forms, and may be set automatically. Several additional items are + * associated with the Account to enable full functionality. + * + * #### Expiration + * Accounts, as most items in the network, have an expiration time, recorded + * as a `Timestamp`, and must be "renewed" for a small fee at expiration. + * This helps to reduce the amount of inactive accounts retained in state. + * Another account may be designated to pay any renewal fees and + * automatically renew the account for (by default) 30-90 days at a time as + * a means to optionally ensure important accounts remain active. + * + * ### Staking + * Accounts may participate in securing the network by "staking" the account + * balances to a particular network node, and receive a portion of network + * fees as a reward. An account may optionally decline these rewards but + * still stake its balances. + * + * #### Transfer Restrictions + * An account may optionally require that inbound transfer transactions be + * signed by that account as receiver (in addition to any other signatures + * required, including sender). + * + */ message AccountInfo { + // Removed prior to oldest available history + reserved 5; + /** - * The account ID for which this information applies + * a unique identifier for this account. + *

+ * An account identifier, when assigned to this field, SHALL be of + * the form `shard.realm.number`. */ 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 + * A Solidity ID. + *

+ * This SHALL be populated if this account is a smart contract, and + * SHALL NOT be populated otherwise.
+ * This SHALL be formatted as a string according to Solidity ID + * standards. */ 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 + * A boolean indicating that this account is deleted. + *

+ * Any transaction involving a deleted account SHALL fail. */ bool deleted = 3; /** - * [Deprecated] 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. + * Replaced by StakingInfo.
+ * ID of the account to which this account is staking its balances. If + * this account is not currently staking its balances, then this field, + * if set, SHALL be the sentinel value of `0.0.0`. */ AccountID proxyAccountID = 4 [deprecated = true]; /** - * The total number of tinybars proxy staked to this account + * Replaced by StakingInfo.
+ * The total amount of tinybar proxy staked to this account. */ - int64 proxyReceived = 6; + int64 proxyReceived = 6 [deprecated = true]; /** - * 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. + * The key to be used to sign transactions from this account, if any. + *

+ * This key SHALL NOT be set for hollow accounts until the account + * is finalized.
+ * This key SHALL be set on all other accounts, except for certain + * immutable accounts (0.0.800 and 0.0.801) necessary for network + * function and otherwise secured by the governing council. */ Key key = 7; /** - * The current balance of account in tinybars + * The HBAR balance of this account, in tinybar (10-8 HBAR). + *

+ * This value SHALL always be a whole number. */ 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 + * Obsolete and unused.
+ * The threshold amount, in tinybars, at which a record was created for + * any transaction that decreased the balance of this account. */ - uint64 generateSendRecordThreshold = 9 [deprecated=true]; + 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 + * Obsolete and unused.
+ * The threshold amount, in tinybars, at which a record was created for + * any transaction that increased the balance of this account. */ - uint64 generateReceiveRecordThreshold = 10 [deprecated=true]; + uint64 generateReceiveRecordThreshold = 10 [deprecated = true]; /** - * If true, no transaction can transfer to this account unless signed by this account's key + * A boolean indicating that the account requires a receiver signature + * for inbound token transfer transactions. + *

+ * If this value is `true` then a transaction to transfer tokens to this + * account SHALL NOT succeed unless this account has signed the + * transfer transaction. */ bool receiverSigRequired = 11; /** - * The TimeStamp time at which this account is set to expire + * The current expiration time for this account. + *

+ * This account SHALL be due standard renewal fees when the network + * consensus time exceeds this time.
+ * If rent and expiration are enabled for the network, and automatic + * renewal is enabled for this account, renewal fees SHALL be charged + * after this time, and, if charged, the expiration time SHALL be + * extended for another renewal period.
+ * This account MAY be expired and removed from state at any point + * after this time if not renewed.
+ * An account holder MAY extend this time by submitting an account + * update transaction to modify expiration time, subject to the current + * maximum expiration time for the network. */ 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. + * A duration to extend this account's expiration. + *

+ * The network SHALL extend the account's expiration by this + * duration, if funds are available, upon automatic renewal.
+ * This SHALL NOT apply if the account is already deleted + * upon expiration.
+ * If this is not provided in an allowed range on account creation, the + * transaction SHALL fail with INVALID_AUTO_RENEWAL_PERIOD. The default + * values for the minimum period and maximum period are currently + * 30 days and 90 days, respectively. */ 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) + * 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; /** - * [DEPRECATED] The metadata of the tokens associated to the account. This field was - * deprecated by HIP-367, which allowed - * an account to be associated to an unlimited number of tokens. This scale makes it more - * efficient for users to consult mirror nodes to review their token associations. + * As of `HIP-367`, which enabled unlimited token associations, the + * potential scale for this value requires that users consult a mirror + * node for this information. */ repeated TokenRelationship tokenRelationships = 15 [deprecated = true]; /** - * The memo associated with the account + * A short description of this account. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 16; /** - * The number of NFTs owned by this account + * The total number of non-fungible/unique tokens owned by this account. */ int64 ownedNfts = 17; /** - * The maximum number of tokens that an Account can be implicitly associated with. + * The maximum number of tokens that can be auto-associated with the + * account. + *

+ * If this is less than or equal to `used_auto_associations` (or 0), + * then this account MUST manually associate with a token before + * transacting in that token.
+ * Following HIP-904 This value may also be `-1` to indicate no + * limit.
+ * This value MUST NOT be less than `-1`. */ int32 max_automatic_token_associations = 18; /** - * The alias of this account + * An account alias.
+ * This is a value used in some contexts to reference an account when + * the tripartite account identifier is not available. + *

+ * This field, when set to a non-default value, is immutable and + * SHALL NOT be changed. */ bytes alias = 19; /** - * The ledger ID the response was returned from; please see HIP-198 for the network-specific IDs. + * The ledger ID of the network that generated this response. + *

+ * This value SHALL identify the distributed ledger that responded to + * this query. */ bytes ledger_id = 20; @@ -177,13 +281,15 @@ message CryptoGetInfoResponse { int64 ethereum_nonce = 21; /** - * Staking metadata for this account. + * Staking information for this account. */ StakingInfo staking_info = 22; } /** - * Info about the account (a state proof can be generated for this) + * Details of the account. + *

+ * A state proof MAY be generated for this field. */ AccountInfo accountInfo = 2; } diff --git a/sdk/src/main/proto/crypto_get_live_hash.proto b/sdk/src/main/proto/crypto_get_live_hash.proto index 1bf80ef32..6c15d7494 100644 --- a/sdk/src/main/proto/crypto_get_live_hash.proto +++ b/sdk/src/main/proto/crypto_get_live_hash.proto @@ -1,13 +1,27 @@ +/** + * # Get Live Hash + * Standard query to inspect associations between content and accounts + * via SHA-384 hashes. + * + * > Important + * >> This query is obsolete and not supported.
+ * >> Any query of this type that is submitted SHALL fail with a `PRE_CHECK` + * >> result of `NOT_SUPPORTED`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +33,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,42 +45,46 @@ import "response_header.proto"; import "crypto_add_live_hash.proto"; /** - * Requests a livehash associated to an account. + * Request detail for a specific live hash associated to a specific 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 information sent with every query operation.
+ * This includes 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 + * An account ID.
+ * The network SHALL return live hash information for this account, + * if successful. */ AccountID accountID = 2; /** - * The SHA-384 data in the livehash + * The specific SHA-384 live hash to inspect */ 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. + * Return the full live hash associated to an account, if it is present. + * + * > Note that to generate a state proof of the _absence_ of a live hash from + * > an account a transaction MUST retrieve a state proof of the `Account` + * > with its list of live hashes. */ message CryptoGetLiveHashResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * The livehash, if present + * The requested live hash, if found. */ LiveHash liveHash = 2; } - - diff --git a/sdk/src/main/proto/crypto_get_stakers.proto b/sdk/src/main/proto/crypto_get_stakers.proto index 44f52eb5a..b837fb737 100644 --- a/sdk/src/main/proto/crypto_get_stakers.proto +++ b/sdk/src/main/proto/crypto_get_stakers.proto @@ -1,13 +1,26 @@ +/** + * # Get Stakers + * Query all of the accounts proxy staking _to_ a specified account. + * + * > Important + * >> This query is obsolete and not supported.
+ * >> Any query of this type that is submitted SHALL fail with a `PRE_CHECK` + * >> result of `NOT_SUPPORTED`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +32,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,13 +43,15 @@ 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 was never implemented. */ message CryptoGetStakersQuery { + option deprecated = true; /** - * 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 information sent with every query operation.
+ * This includes the signed payment and what kind of response is requested + * (cost, state proof, both, or neither). */ QueryHeader header = 1; @@ -51,6 +65,7 @@ message CryptoGetStakersQuery { * information about a single account that is proxy staking */ message ProxyStaker { + option deprecated = true; /** * The Account ID that is proxy staking */ @@ -63,9 +78,11 @@ message ProxyStaker { } /** - * 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 { + option deprecated = true; /** * The Account ID that is being proxy staked to */ @@ -81,15 +98,17 @@ message AllProxyStakers { * Response when the client sends the node CryptoGetStakersQuery */ message CryptoGetStakersResponse { + option deprecated = true; /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * List of accounts proxy staking to this account, and the amount each is currently proxy - * staking + * List of accounts proxy staking to this account, and the amount each is + * currently proxy staking */ AllProxyStakers stakers = 3; } diff --git a/sdk/src/main/proto/crypto_service.proto b/sdk/src/main/proto/crypto_service.proto index 226943555..fa390d4eb 100644 --- a/sdk/src/main/proto/crypto_service.proto +++ b/sdk/src/main/proto/crypto_service.proto @@ -1,13 +1,29 @@ +/** + * # Crypto Service + * A service defining transactions and queries related to accounts. + * + * This includes transactions for HBAR transfers and balance queries as well as + * transactions to manage "allowances" which permit a third party to spend a + * portion of the HBAR balance in an account.
+ * Basic account, record, and receipt queries are also defined in this service. + * + * Transactions and queries relating to tokens _other than HBAR_ are defined + * in the Token Service. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,8 +35,8 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ + option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package @@ -30,90 +46,94 @@ import "transaction_response.proto"; import "transaction.proto"; /** - * Transactions and queries for the Crypto Service + * Transactions and queries for the Hedera Crypto Service. */ service CryptoService { + // The following queries are permanently removed. + // getStakersByAccountID, getFastTransactionRecord + /** - * Creates a new account by submitting the transaction + * Create a new account by submitting the transaction */ rpc createAccount (Transaction) returns (TransactionResponse); /** - * Updates an account by submitting the transaction + * Update an account by submitting the transaction */ rpc updateAccount (Transaction) returns (TransactionResponse); /** - * Initiates a transfer by submitting the transaction + * Initiate a transfer by submitting the transaction */ rpc cryptoTransfer (Transaction) returns (TransactionResponse); /** - * Deletes and account by submitting the transaction + * Delete an account by submitting the transaction */ rpc cryptoDelete (Transaction) returns (TransactionResponse); /** - * Adds one or more approved allowances for spenders to transfer the paying account's hbar or tokens. + * Add one or more approved allowances for spenders to transfer the paying + * account's hbar or tokens. */ rpc approveAllowances (Transaction) returns (TransactionResponse); /** - * Deletes one or more of the specific approved NFT serial numbers on an owner account. + * Delete one or more of the specific approved NFT serial numbers on an + * owner account. */ rpc deleteAllowances (Transaction) returns (TransactionResponse); /** - * (NOT CURRENTLY SUPPORTED) Adds a livehash + * Add a livehash + *

Important
+ * This transaction is obsolete, not supported, and SHALL fail with a + * pre-check result of `NOT_SUPPORTED`.
*/ - rpc addLiveHash (Transaction) returns (TransactionResponse); + rpc addLiveHash (Transaction) returns (TransactionResponse) {option deprecated = true;}; /** - * (NOT CURRENTLY SUPPORTED) Deletes a livehash + * Delete a livehash + *
Important
+ * This transaction is obsolete, not supported, and SHALL fail with a + * pre-check result of `NOT_SUPPORTED`.
*/ - rpc deleteLiveHash (Transaction) returns (TransactionResponse); + rpc deleteLiveHash (Transaction) returns (TransactionResponse) {option deprecated = true;}; /** - * (NOT CURRENTLY SUPPORTED) Retrieves a livehash for an account + * Retrieve a livehash for an account + *
Important
+ * This query is obsolete, not supported, and SHALL fail with a pre-check + * result of `NOT_SUPPORTED`.
*/ - rpc getLiveHash (Query) returns (Response); + rpc getLiveHash (Query) returns (Response) {option deprecated = 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. + * Return 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 + * Retrieve the balance of an account */ rpc cryptoGetBalance (Query) returns (Response); /** - * Retrieves the metadata of an account + * Retrieve 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 + * Retrieve 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 - */ - rpc getFastTransactionRecord (Query) returns (Response); - - /** - * Retrieves the record of a transaction that is either awaiting consensus, or reached consensus - * in the last 180 seconds + * Retrieve 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 - */ - rpc getStakersByAccountID (Query) returns (Response); } diff --git a/sdk/src/main/proto/crypto_transfer.proto b/sdk/src/main/proto/crypto_transfer.proto index 065daec8d..773c2807d 100644 --- a/sdk/src/main/proto/crypto_transfer.proto +++ b/sdk/src/main/proto/crypto_transfer.proto @@ -1,13 +1,22 @@ +/** + * # Crypto Transfer + * Transaction to transfer HBAR between accounts, or between accounts and + * smart contracts. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,26 +37,60 @@ 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. + * Transfer HBAR and/or other tokens among two or more accounts and/or smart + * contracts. + * + * Transfers of HBAR or fungible/common tokens in this transaction are + * structured as a "double-entry" transfer list which debits one or more + * accounts, and separately credits one or more accounts. Each such transfer + * list may specify up to 10 individual credits or debits.
+ * Transfers of non-fungible/unique tokens in this transaction are + * structured as a "single-entry" transfer list, which both debits one account + * and credits another account in a single entry. + * + * At least one transfer MUST be present, this MAY be an HBAR transfer in + * `transfers`, or MAY be a token transfer in `tokenTransfers`.
+ * Either `transfers` or `tokenTransfers` MAY be unset, provided the other + * is set and not empty.
+ * If any one account with a debit in any transfer list holds insufficient + * balance to complete the transfer, the entire transaction SHALL fail, and + * all transfers SHALL NOT be completed.
+ * If any one account that is _sending_ an individual non-fungible/unique (NFT) + * token does not currently hold that unique NFT, the entire transaction SHALL + * FAIL, and all transfers SHALL NOT be completed. + * The transaction fee SHALL be charged for a transaction that fails due to + * insufficient balance or not holding the NFT to be transferred.
+ * Each account with any debit amounts in any transfer list MUST sign this + * transaction.
+ * Each account with any credit amounts in any transfer list that also has the + * `receiverSigRequired` flag set MUST sign this transaction. + * + * ### Block Stream Effects + * All debits and credits completed by this transaction SHALL be included in + * the transaction result transfer list.
+ * Multiple fungible/common debits from one account, or credits to one account, + * MAY be consolidated to a single debit or credit entry in the + * transaction result.
+ * Multiple non-fungible/unique transfers SHALL NOT be consolidated in the + * transaction result. */ message CryptoTransferTransactionBody { /** - * The desired hbar balance adjustments + * A list of HBAR transfers. + *

+ * Each transfer in this list MUST be denominated in tinybar. */ 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 + * One or more lists of token transfers. + *

+ * This list MUST NOT contain more than 10 entries.
+ * If custom fees must be charged, the fee SHALL be assessed against the + * effective "payer" for this transaction.
+ * If the effective "payer" for this transaction lacks sufficient balance + * to pay custom fees assessed, the entire transaction SHALL fail with a + * response code `INSUFFICIENT_PAYER_BALANCE_FOR_CUSTOM_FEE`. */ repeated TokenTransferList tokenTransfers = 2; } diff --git a/sdk/src/main/proto/crypto_update.proto b/sdk/src/main/proto/crypto_update.proto index 019606b9f..c173abef2 100644 --- a/sdk/src/main/proto/crypto_update.proto +++ b/sdk/src/main/proto/crypto_update.proto @@ -1,13 +1,21 @@ +/** + * # Crypto Update + * Modify a single account. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,131 +39,196 @@ 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. - * If the update transaction sets the auto_renew_account field to anything other - * than the sentinel 0.0.0, the key of the referenced account must sign. + * Modify the current state of an account. + * + * ### Requirements + * - The `key` for this account MUST sign all account update transactions. + * - If the `key` field is set for this transaction, then _both_ the current + * `key` and the new `key` MUST sign this transaction, for security and to + * prevent setting the `key` field to an invalid value. + * - If the `auto_renew_account` field is set for this transaction, the account + * identified in that field MUST sign this transaction. + * - Fields set to non-default values in this transaction SHALL be updated on + * success. Fields not set to non-default values SHALL NOT be + * updated on success. + * - All fields that may be modified in this transaction SHALL have a + * default value of unset (a.k.a. `null`). + * + * ### Block Stream Effects + * None */ message CryptoUpdateTransactionBody { + // NOTE: Seven deprecated fields should probably be removed and the + // field names reserved. + // reserved 4,5,6,7,10,11,12 + // Also, the `receiverSigRequiredField` oneOf should be removed + // around `receiverSigRequiredWrapper` and the field renamed + // (both actions are "safe" in protobuf) to `receiver_signature_required`. + /** - * The account ID which is being updated in this transaction + * An account identifier.
+ * This identifies the account which is to be modified in this transaction. + *

+ * This field is REQUIRED. */ AccountID accountIDToUpdate = 2; /** - * The new key + * An account key.
+ * This may be a "primitive" key (a singly cryptographic key), or a + * composite key. + *

+ * If set, this key MUST be a valid key.
+ * If set, the previous key and new key MUST both sign this transaction. */ Key key = 3; /** - * [Deprecated] 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. + * Removed in favor of the `staked_id` oneOf.
+ * An account identifier for a "proxy" account. This account's HBAR are + * staked to a node selected by the proxy account. */ AccountID proxyAccountID = 4 [deprecated = true]; /** - * [Deprecated]. Payments earned from proxy staking are shared between the node and this - * account, with proxyFraction / 10000 going to this account + * Removed prior to the first available history.
+ * A fraction to split staking rewards between this account and the proxy + * account. */ int32 proxyFraction = 5 [deprecated = true]; + // This entire oneOf is deprecated, and the concept is not implemented. oneof sendRecordThresholdField { /** - * [Deprecated]. The new threshold amount (in tinybars) for which an account record is + * Removed prior to the first available history, and may be related + * to an early design dead-end.
+ * 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 + * Removed prior to the first available history, and may be related + * to an early design dead-end.
+ * 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]; } + // This entire oneOf is deprecated, and the concept is not implemented. oneof receiveRecordThresholdField { /** - * [Deprecated]. The new threshold amount (in tinybars) for which an account record is + * Removed prior to the first available history, and may be related + * to an early design dead-end.
+ * 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 + * Removed prior to the first available history, and may be related + * to an early design dead-end.
+ * 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]; } /** - * 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. + * A duration to extend account expiration.
+ * An amount of time, in seconds, to extend the expiration date for this + * account when _automatically_ renewed. + *

+ * This duration MUST be between the current configured minimum and maximum + * values defined for the network.
+ * This duration SHALL be applied only when _automatically_ extending the + * account expiration. */ Duration autoRenewPeriod = 8; /** - * The new expiration time to extend to (ignored if equal to or before the current one) + * A new account expiration time, in seconds since the epoch. + *

+ * For this purpose, `epoch` SHALL be the UNIX epoch with 0 + * at `1970-01-01T00:00:00.000Z`.
+ * If set, this value MUST be later than the current consensus time.
+ * If set, this value MUST be earlier than the current consensus time + * extended by the current maximum expiration time configured for the + * network. */ Timestamp expirationTime = 9; oneof receiverSigRequiredField { /** - * [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. + * Removed to distinguish between unset and a default value.
+ * 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) + * A flag indicating the account holder must authorize all incoming + * token transfers. + *

+ * If this flag is set then any transaction that would result in adding + * hbar or other tokens to this account balance MUST be signed by the + * identifying key of this account (that is, the `key` field). */ google.protobuf.BoolValue receiverSigRequiredWrapper = 13; } /** - * If set, the new memo to be associated with the account (UTF-8 encoding max 100 bytes) + * A short description of this Account. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ google.protobuf.StringValue memo = 14; /** - * If set, modify the maximum number of tokens that can be auto-associated with the - * account.
- * If this is set and less than or equal to `used_auto_associations`, or 0, then this account - * MUST manually associate with a token before transacting in that token.
+ * A maximum number of tokens that can be auto-associated + * with this account.
+ * By default this value is 0 for all accounts except for automatically + * created accounts (i.e smart contracts) which default to -1. + *

+ * If this value is `0`, then this account MUST manually associate to + * a token before holding or transacting in that token.
* This value MAY also be `-1` to indicate no limit.
- * This value MUST NOT be less than `-1`. + * If set, this value MUST NOT be less than `-1`.
*/ google.protobuf.Int32Value max_automatic_token_associations = 15; - /** - * ID of the account or node to which this account is staking. - */ oneof staked_id { - /** - * ID of the new account to which this account is staking. If set to the sentinel 0.0.0 AccountID, - * this field removes this account's staked account ID. + * ID of the account to which this account is staking its balances. + *

+ * If this account is not currently staking its balances, then this + * field, if set, MUST be the sentinel value of `0.0.0`. */ AccountID staked_account_id = 16; /** - * ID of the new node this account is staked to. If set to the sentinel -1, this field - * removes this account's staked node ID. + * ID of the node this account is staked to. + *

+ * If this account is not currently staking its balances, then this + * field, if set, SHALL be the sentinel value of `-1`.
+ * Wallet software SHOULD surface staking issues to users and provide a + * simple mechanism to update staking to a new node ID in the event the + * prior staked node ID ceases to be valid. */ int64 staked_node_id = 17; } /** - * If true, the account declines receiving a staking reward. The default value is false. + * A boolean indicating that this account has chosen to decline rewards for + * staking its balances. + *

+ * This account MAY still stake its balances, but SHALL NOT receive reward + * payments for doing so, if this value is set, and `true`. */ google.protobuf.BoolValue decline_reward = 18; + } diff --git a/sdk/src/main/proto/custom_fees.proto b/sdk/src/main/proto/custom_fees.proto index a15c10f8a..c693ef63d 100644 --- a/sdk/src/main/proto/custom_fees.proto +++ b/sdk/src/main/proto/custom_fees.proto @@ -1,13 +1,22 @@ +/** + * # Custom Fees + * Fees defined by token creators that are charged as part of each + * transfer of that token type. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,147 +37,386 @@ 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 descriptor for a fee based on a portion of the tokens transferred. + * + * This fee option describes fees as a fraction of the amount of + * fungible/common token(s) transferred. The fee also describes a minimum + * and maximum amount, both of which are OPTIONAL. + * + * This type of fee SHALL be assessed only for fungible/common tokens.
+ * This type of fee MUST NOT be defined for a non-fungible/unique + * token type.
+ * This fee SHALL be paid with the same type of tokens as those + * transferred.
+ * The fee MAY be subtracted from the transferred tokens, or MAY be assessed + * to the sender in addition to the tokens actually transferred, based on + * the `net_of_transfers` field. + * + * When a single transaction sends tokens from one sender to multiple + * recipients, and the `net_of_transfers` flag is false, the network + * SHALL attempt to evenly assess the total fee across all recipients + * proportionally. This may be inexact and, particularly when there are + * large differences between recipients, MAY result in small deviations + * from an ideal "fair" distribution.
+ * If the sender lacks sufficient tokens to pay fees, or the assessment + * of custom fees reduces the net amount transferred to or below zero, + * the transaction MAY fail due to insufficient funds to pay all fees. */ message FractionalFee { - /** - * The fraction of the transferred units to assess as a fee - */ - Fraction fractional_amount = 1; + /** + * A Fraction of the transferred tokens to assess as a fee.
+ * This value MUST be less than or equal to one.
+ * This value MUST be greater than zero. + */ + Fraction fractional_amount = 1; - /** - * The minimum amount to assess - */ - int64 minimum_amount = 2; + /** + * A minimum fee to charge, in units of 10-decimals tokens. + *

+ * This value is OPTIONAL, with a default of `0` indicating no minimum.
+ * If set, this value MUST be greater than zero.
+ * If set, all transfers SHALL pay at least this amount. + */ + int64 minimum_amount = 2; - /** - * The maximum amount to assess (zero implies no maximum) - */ - int64 maximum_amount = 3; + /** + * A maximum fee to charge, in units of 10-decimals tokens. + *

+ * This value is OPTIONAL, with a default of `0` indicating no maximum.
+ * If set, this value MUST be greater than zero.
+ * If set, any fee charged SHALL NOT exceed this value.
+ * This value SHOULD be strictly greater than `minimum_amount`. + * If this amount is less than or equal to `minimum_amount`, then + * the fee charged SHALL always be equal to this value and + * `fractional_amount` SHALL NOT have any effect. + */ + 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; + /** + * Flag requesting to assess the calculated fee against the sender, + * without reducing the amount transferred.
+ * #### Effects of this flag + *

    + *
  1. If this value is true + *
      + *
    • The receiver of a transfer SHALL receive the entire + * amount sent.
      • + *
    • The fee SHALL be charged to the sender as an additional + * amount, increasing the token transfer debit.
      • + *
    + *
    2. + *
  2. If this value is false + *
      + *
    • The receiver of a transfer SHALL receive the amount sent + * _after_ deduction of the calculated fee.
      • + *
    + *
    3. + *
+ */ + 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 fee to assess for each token transfer, regardless of the + * amount transferred.
+ * This fee type describes a fixed fee for each transfer of a token type. + * + * The fee SHALL be charged to the `sender` for the token transfer + * transaction.
+ * This fee MAY be assessed in HBAR, the token type transferred, or any + * other token type, as determined by the `denominating_token_id` field. */ message FixedFee { - /** - * The number of units to assess as a fee - */ - int64 amount = 1; + /** + * The amount to assess for each transfer. + *

+ * This value MUST be greater than `0`.
+ * This amount is expressed in units of 10-decimals tokens. + */ + 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; + /** + * The token type used to pay the assessed fee. + *

+ * If this is unset, the fee SHALL be assessed in HBAR.
+ * If this is set, the fee SHALL be assessed in the token identified. + * This MAY be any token type. Custom fees assessed in other token types + * are more likely to fail, however, and it is RECOMMENDED that token + * creators denominate custom fees in the transferred token, HBAR, or + * well documented and closely related token types.
+ * If this value is set to `0.0.0` in the `tokenCreate` transaction, it + * SHALL be replaced with the `TokenID` of the newly created token. + */ + 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. - * - * **IMPORTANT:** Users must understand that native royalty fees are _strictly_ a convenience feature, - * and that the network cannot enforce inescapable royalties on the exchange of a non-fractional NFT. - * For example, if the counterparties agree to split their value transfer and NFT exchange into separate - * transactions, the network cannot possibly intervene. (And note the counterparties could use a smart - * contract to make this split transaction atomic if they do not trust each other.) + * A fee to assess during a CryptoTransfer that changes ownership of a + * non-fungible/unique (NFT) token.
+ * This message defines the fraction of the fungible value exchanged for an + * NFT that the ledger should collect as a royalty. + * "Fungible value" includes both HBAR (ℏ) 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 non-fungible/unique tokens. * - * Counterparties that _do_ wish to respect creator royalties should follow the pattern the network - * recognizes: The NFT sender and receiver should both sign a single `CryptoTransfer` that credits - * the sender with all the fungible value the receiver is exchanging for the NFT. + * #### Important Note + * > Users should be aware that native royalty fees are _strictly_ a + * > convenience feature, SHALL NOT be guaranteed, and the network SHALL NOT + * > enforce _inescapable_ royalties on the exchange of a unique NFT.
+ * > For _one_ example, if the counterparties agree to split their value + * > transfer and NFT exchange into separate transactions, the network cannot + * > possibly determine the value exchanged. Even trustless transactions, + * > using a smart contract or other form of escrow, can arrange such split + * > transactions as a single _logical_ transfer. * - * Similarly, a marketplace using an approved spender account for an escrow transaction should credit - * the account selling the NFT in the same `CryptoTransfer` that deducts fungible value from the buying - * account. + * Counterparties that wish to _respect_ creator royalties MUST follow the + * pattern the network recognizes. + *

+ * A single transaction MUST contain all three elements, transfer of the NFT, + * debit of fungible value from the receiver, and credit of fungible value to + * the sender, in order for the network to accurately assess royalty fees. + *
+ *
+ * Two examples are presented here. + *
+ * The NFT sender and receiver MUST both sign a single `cryptoTransfer` that + * transfers the NFT from sender to receiver, debits the fungible value from + * the receiver, and credits the sender with the fungible value the receiver + * is exchanging for the NFT.
+ * A marketplace using an approved spender account for an escrow transaction + * MUST credit the account selling the NFT in the same `cryptoTransfer` + * transaction that transfers the NFT to, and deducts fungible value from, + * the buying account. + *
+ * This type of fee MAY NOT produce accurate results if multiple transfers + * are executed in a single transaction. It is RECOMMENDED that each + * NFT subject to royalty fees be transferred separately and without + * unrelated fungible token transfers. * - * There is an [open HIP discussion](https://github.com/hashgraph/hedera-improvement-proposal/discussions/578) - * that proposes to broaden the class of transactions for which the network automatically collects - * royalties. If this interests or concerns you, please add your voice to that discussion. + * The network SHALL NOT consider third-party transfers, including + * "approved spender" accounts, in collecting royalty fees. An honest + * broker MUST ensure that transfer of an NFT and payment delivered to + * the sender are present in the same transaction. + * There is an + * [open suggestion](https://github.com/hashgraph/hedera-improvement-proposal/discussions/578) + * that proposes to broaden the scope of transfers from which the network + * automatically collects royalties to cover related third parties. If this + * interests or concerns you, please add your voice to that discussion. */ message RoyaltyFee { - /** - * The fraction of fungible value exchanged for an NFT to collect as royalty - */ - Fraction exchange_value_fraction = 1; + /** + * The fraction of fungible value exchanged for an NFT to collect + * as royalty. + *

+ * This SHALL be applied once to the total fungible value transferred + * for the transaction.
+ * There SHALL NOT be any adjustment based on multiple transfers + * involving the NFT sender as part of a single transaction. + */ + 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 fixed fee to assess if no fungible value is known to be traded + * for the NFT. + *

+ * If an NFT is transferred without a corresponding transfer of + * _fungible_ value returned in the same transaction, the network + * SHALL charge this fee as a fallback.
+ * Fallback fees MAY have unexpected effects when interacting with + * escrow, market transfers, and smart contracts. + * It is RECOMMENDED that developers carefully consider possible + * effects from fallback fees when designing systems that facilitate + * the transfer of NFTs. + */ + 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.
+ * This fee applies to transactions that transfer 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. + * + * Custom fees MUST be greater than zero (0). */ message CustomFee { - oneof fee { + oneof fee { + /** + * A fixed fee to be charged to the `sender` for every token transfer. + *

+ * This type of fee MAY be defined for any token type.
+ * This type of fee MAY be more consistent and reliable than + * other types. + */ + FixedFee fixed_fee = 1; + + /** + * A fee defined as a fraction of the tokens transferred. + *

+ * This type of fee MUST NOT be defined for a non-fungible/unique + * token type.
+ * This fee MAY be charged to either sender, as an increase to the + * amount sent, or receiver, as a reduction to the amount received. + */ + FractionalFee fractional_fee = 2; + + /** + * A fee charged as royalty for any transfer of a + * non-fungible/unique token. + *

+ * This type of fee MUST NOT be defined for a + * fungible/common token type. + */ + RoyaltyFee royalty_fee = 4; + + } /** - * Fixed fee to be charged + * The account to receive the custom fee. */ - FixedFee fixed_fee = 1; + AccountID fee_collector_account_id = 3; /** - * Fractional fee to be charged + * Flag indicating to exempt all custom fee collector accounts for this + * token type from paying this custom fee when sending tokens. + *

+ * The treasury account for a token, and the account identified by the + * `fee_collector_account_id` field of this `CustomFee` are always exempt + * from this custom fee to avoid redundant and unnecessary transfers. + * If this value is `true` then the account(s) identified in + * `fee_collector_account_id` for _all_ custom fee definitions for this + * token type SHALL also be exempt from this custom fee. + * This behavior is specified in HIP-573. */ - FractionalFee fractional_fee = 2; + bool all_collectors_are_exempt = 5; +} +/** + * Description of a transfer added to a `cryptoTransfer` transaction that + * satisfies custom fee requirements. + * + * It is important to note that this is not the actual transfer. The transfer + * of value SHALL be merged into the original transaction to minimize the + * number of actual transfers. This descriptor presents the fee assessed + * separately in the record stream so that the details of the fee assessed + * are not hidden in this process. + */ +message AssessedCustomFee { /** - * Royalty fee to be charged + * An amount of tokens assessed for this custom fee. + *

+ * This shall be expressed in units of 10-decimals tokens. */ - RoyaltyFee royalty_fee = 4; + int64 amount = 1; - } - /** - * The account to receive the custom fee - */ - AccountID fee_collector_account_id = 3; + /** + * The token transferred to satisfy this fee. + *

+ * If the token transferred is HBAR, this field SHALL NOT be set. + */ + TokenID token_id = 2; - /** - * If true, exempts all the token's fee collection accounts from this fee. - * (The token's treasury and the above fee_collector_account_id will always - * be exempt. Please see HIP-573 - * for details.) - */ - bool all_collectors_are_exempt = 5; + /** + * An account that received the fee assessed. + *

+ * This SHALL NOT be the sender or receiver of the original + * cryptoTransfer transaction. + */ + AccountID fee_collector_account_id = 3; + + /** + * An account that provided the tokens assessed as a fee. + *

+ * This SHALL be the account that _would have_ had a higher balance + * absent the fee. In most cases this SHALL be the `sender`, but + * some _fractional_ fees reduce the amount transferred, and in those + * cases the `receiver` SHALL be the effective payer for the fee.
+ * There are currently no situations where a third party pays a custom + * fee. This MAY change in a future release. + */ + repeated AccountID effective_payer_account_id = 4; } /** - * A custom transfer fee that was assessed during handling of a CryptoTransfer. + * A custom fee definition for a consensus topic. + *

+ * This fee definition is specific to an Hedera Consensus Service (HCS) topic + * and SHOULD NOT be used in any other context.
+ * All fields for this message are REQUIRED.
+ * Only "fixed" fee definitions are supported because there is no basis for + * a fractional fee on a consensus submit transaction. */ -message AssessedCustomFee { +message FixedCustomFee { /** - * The number of units assessed for the fee + * A fixed custom fee. + *

+ * The amount of HBAR or other token described by this `FixedFee` SHALL + * be charged to the transction payer for each message submitted to a + * topic that assigns this consensus custom fee. */ - int64 amount = 1; + FixedFee fixed_fee = 1; /** - * The denomination of the fee; taken as hbar if left unset + * A collection account identifier. + *

+ * All amounts collected for this consensus custom fee SHALL be transferred + * to the account identified by this field. */ - TokenID token_id = 2; + AccountID fee_collector_account_id = 2; +} +/** + * A wrapper around a consensus custom fee list.
+ * This wrapper exists to enable an update transaction to differentiate between + * a field that is not set and an empty list of custom fees. + *

+ * An _unset_ field of this type SHALL NOT modify existing values.
+ * A _set_ field of this type with an empty `fees` list SHALL remove any + * existing values. + */ +message FixedCustomFeeList { /** - * The account to receive the assessed fee + * A set of custom fee definitions.
+ * These are fees to be assessed for each submit to a topic. */ - AccountID fee_collector_account_id = 3; + repeated FixedCustomFee fees = 1; +} +/** + * A wrapper for fee exempt key list.
+ * This wrapper exists to enable an update transaction to differentiate between + * a field that is not set and an empty list of keys. + *

+ * An _unset_ field of this type SHALL NOT modify existing values.
+ * A _set_ field of this type with an empty `keys` list SHALL remove any + * existing values. + */ +message FeeExemptKeyList { /** - * The account(s) whose final balances would have been higher in the absence of this assessed fee + * A set of keys.
+ * The keys in this list are permitted to submit messages to the + * topic without paying the topic's custom fees. + *

+ * If a submit transaction is signed by _any_ key included in this set, + * custom fees SHALL NOT be charged for that transaction. */ - repeated AccountID effective_payer_account_id = 4; + repeated Key keys = 1; +} + +/** + * A maximum custom fee that the user is willing to pay. + *

+ * This message is used to specify the maximum custom fee that given user is + * willing to pay. + */ +message CustomFeeLimit { + /** + * A payer account identifier. + */ + AccountID account_id = 1; + + /** + * The maximum fees that the user is willing to pay for the message. + */ + repeated FixedFee fees = 2; } diff --git a/sdk/src/main/proto/duration.proto b/sdk/src/main/proto/duration.proto index 0883f7d59..a3a89520a 100644 --- a/sdk/src/main/proto/duration.proto +++ b/sdk/src/main/proto/duration.proto @@ -1,13 +1,21 @@ +/** + * # Duration + * A duration, in seconds. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -28,10 +35,13 @@ option java_multiple_files = true; /** * A length of time in seconds. + * + * It is RECOMMENDED that this message be used whenever an amount of time, + * rather than a specific point in time, is needed. */ message Duration { /** - * The number of seconds + * The number of seconds for this duration. */ int64 seconds = 1; } diff --git a/sdk/src/main/proto/entity_counts.proto b/sdk/src/main/proto/entity_counts.proto new file mode 100644 index 000000000..922499b6e --- /dev/null +++ b/sdk/src/main/proto/entity_counts.proto @@ -0,0 +1,89 @@ +syntax = "proto3"; + +package com.hedera.hapi.node.state.entity; +/* + * Copyright (C) 2025 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * This proto file contains primitive value messages. + * These are intended only for situations where the entire value to be stored in state is a single + * primitive. These should never be used as components of another message; use the protobuf + * type instead. + */ + +option java_package = "com.hedera.hashgraph.sdk.proto"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * Representation of a Hedera Entity Service entity counts in the network Merkle tree. + * + * This message is used to store the counts of various entities in the network. + */ +message EntityCounts { + /** + * The number of accounts in the network. + */ + uint64 num_accounts = 1; + /** + * The number of aliases in the network. + */ + uint64 num_aliases = 2; + /** + * The number of tokens in the network. + */ + uint64 num_tokens = 3; + /** + * The number of token relationships in the network. + */ + uint64 num_token_relations = 4; + /** + * The number of NFTs in the network. + */ + uint64 num_nfts = 5; + /** + * The number of airdrops in the network. + */ + uint64 num_airdrops = 6; + /** + * The number of staking infos in the network. + */ + uint64 num_staking_infos = 7; + /** + * The number of topics in the network. + */ + uint64 num_topics = 8; + /** + * The number of files in the network. + */ + uint64 num_files = 9; + /** + * The number of nodes in the network. + */ + uint64 num_nodes = 10; + /** + * The number of schedules in the network. + */ + uint64 num_schedules = 11; + /** + * The number of contract storage slots in the network. + */ + uint64 num_contract_storage_slots = 12; + /** + * The number of contract bytecodes in the network. + */ + uint64 num_contract_bytecodes = 13; +} \ No newline at end of file diff --git a/sdk/src/main/proto/ethereum_transaction.proto b/sdk/src/main/proto/ethereum_transaction.proto index f50d1ea99..b908d384c 100644 --- a/sdk/src/main/proto/ethereum_transaction.proto +++ b/sdk/src/main/proto/ethereum_transaction.proto @@ -1,13 +1,26 @@ +/** + * # Ethereum Call + * Make an Ethereum transaction "call" with all data in Ethereum formats, + * including the contract alias. Call data may be in the transaction, + * or stored within an Hedera File.
+ * The caller MAY offer additional gas above what is offered in the call + * data, but MAY be charged up to 80% of that value if the amount required + * is less than this "floor" amount. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2022 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +32,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -28,36 +40,72 @@ option java_multiple_files = true; import "basic_types.proto"; +/** + * A transaction in Ethereum format.
+ * Make an Ethereum transaction "call" with all data in Ethereum formats, + * including the contract alias. Call data may be in the transaction, or + * stored within an Hedera File. + * + * The caller MAY offer additional gas above what is offered in the call data, + * but MAY be charged up to 80% of that value if the amount required is less + * than this "floor" amount. + * + * ### Block Stream Effects + * An `EthereumOutput` message SHALL be emitted for each transaction. + */ message EthereumTransactionBody { - /** - * The raw Ethereum transaction (RLP encoded type 0, 1, and 2). Complete - * unless the callData field is set. - */ - bytes ethereum_data = 1; - - /** - * For large transactions (for example contract create) this is the callData - * of the ethereumData. The data in the ethereumData will be re-written with - * the callData element as a zero length string with the original contents in - * the referenced file at time of execution. The ethereumData will need to be - * "rehydrated" with the callData for signature validation to pass. - */ - FileID call_data = 2; - - /** - * The maximum amount, in tinybars, that the payer of the hedera transaction - * is willing to pay to complete the transaction. - * - * Ordinarily the account with the ECDSA alias corresponding to the public - * key that is extracted from the ethereum_data signature is responsible for - * fees that result from the execution of the transaction. If that amount of - * authorized fees is not sufficient then the payer of the transaction can be - * charged, up to but not exceeding this amount. If the ethereum_data - * transaction authorized an amount that was insufficient then the payer will - * only be charged the amount needed to make up the difference. If the gas - * price in the transaction was set to zero then the payer will be assessed - * the entire fee. - */ - int64 max_gas_allowance = 3; + /** + * The raw Ethereum transaction data. + *

+ * This transaction MUST be RLP encoded.
+ * This SHALL be the complete transaction data unless the `call_data` + * field is set.
+ * If `call_data` is set, this field SHALL be modified to replace the + * `callData` element with the content of the referenced file.
+ * The transaction signature SHALL be validated after `callData` is + * complete, if necessary. + */ + bytes ethereum_data = 1; + + /** + * The `callData` for the Ethereum transaction. + *

+ * If this field is set, the data in the `ethereum_data` field SHALL be + * re-written to replace the `callData` element with the contents of this + * file at time of execution.
+ * The Ethereum transaction MUST be "rehydrated" with this modified + * `callData` before signature validation MAY be performed. + */ + FileID call_data = 2; + + /** + * A maximum amount of "gas" offered to pay the Ethereum transaction costs. + *

+ * This gas offered is in addition to any gas supplied with the Ethereum + * transaction as declared in the `ethereum_data`.
+ * In most circumstances the account with an alias matching the public + * key available from the Ethereum transaction signature offers sufficient + * gas to power the transaction, but in some cases it MAY be desirable + * for the account submitting this transaction to either supplement + * or entirely fund the transaction cost.
+ * The amount of gas offered here SHALL be used to pay for + * transaction costs _in excess_ of any gas offered within + * the Ethereum transaction.
+ * If the gas offered within the Ethereum transaction is sufficient + * for all costs, the gas offered in this field SHALL NOT be expended.
+ * Regardless of actual transaction cost, the payer for this transaction + * SHALL NOT be charged more gas than the amount offered here.
+ * If the sum of both gas amounts is not sufficient to pay for the + * transaction, the entire total amount of gas offered SHALL be expended, + * the transaction SHALL fail, and the response code `INSUFFICIENT_GAS` + * SHALL be set.
+ * If any amount of gas is charged to the payer of this transaction, + * at least 80% of the value offered in this field SHALL be charged + * as a minimum fee.
+ * If the amount of gas authorized in the Ethereum transaction data is `0`, + * then the payer of this transaction SHALL be charged the entire cost of + * the Ethereum transaction, subject to the limit set in this field. + */ + int64 max_gas_allowance = 3; } diff --git a/sdk/src/main/proto/event_consensus_data.proto b/sdk/src/main/proto/event_consensus_data.proto new file mode 100644 index 000000000..0a060d6e7 --- /dev/null +++ b/sdk/src/main/proto/event_consensus_data.proto @@ -0,0 +1,69 @@ +/** + * # Event Consensus Data + * A message that describes the consensus data for an event. + * + * The `EventConsensusData` contains two fields that are determined once an + * event reaches consensus, the `consensus_timestamp` and `consensus_order`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119). + */ +syntax = "proto3"; + +package com.hedera.hapi.platform.event; + +/* + * Hedera Network Services Protobuf + * + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import "basic_types.proto"; +import "event_descriptor.proto"; +import "timestamp.proto"; + +option java_package = "com.hedera.hapi.platform.event.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * Event Consensus Data.
+ * This message records the critical values produced by consensus for an event. + */ +message EventConsensusData { + /** + * A consensus timestamp.
+ * The network's consensus agreement on a timestamp for this event. + *

+ * This timestamp MUST be strictly greater than the `consensus_timestamp` of + * the previous consensus event.
+ * This is a consensus value and MAY NOT match real-world "wall clock" time. + */ + proto.Timestamp consensus_timestamp = 1; + + /** + * A consensus order sequence number.
+ * A non-negative sequence number that identifies an event's consensus order + * since genesis. + *

+ * This SHALL be the unique for each consensus event.
+ * This SHALL always increase, and SHALL NOT decrease.
+ * This SHALL increment by one for each consensus event. + */ + uint64 consensus_order = 2; +} + diff --git a/sdk/src/main/proto/event_core.proto b/sdk/src/main/proto/event_core.proto new file mode 100644 index 000000000..2392e16af --- /dev/null +++ b/sdk/src/main/proto/event_core.proto @@ -0,0 +1,83 @@ +/** + * # Core Event Data + * A message that describes the metadata for an event. + * + * The `EventCore` contains a list of the event's parents, as well as the software + * version, an identifier for the node that created this event, the birth round, and + * the creation timestamp for the event. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119). + */ +syntax = "proto3"; + +package com.hedera.hapi.platform.event; + +/* + * Hedera Network Services Protobuf + * + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import "basic_types.proto"; +import "event_descriptor.proto"; +import "timestamp.proto"; + +option java_package = "com.hedera.hapi.platform.event.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * Contains information about an event and its parents. + */ +message EventCore { + /** + * The creator node identifier.
+ * This SHALL be the unique identifier for the node that created the event.
+ * This SHALL match the ID of the node as it appears in the address book. + */ + int64 creator_node_id = 1; + + /** + * The birth round of the event.
+ * The birth round SHALL be the pending consensus round at the time the event is created.
+ * The pending consensus round SHALL be **one greater** than the latest round to reach consensus. + */ + int64 birth_round = 2; + + /** + * The wall clock time at which the event was created, according to the node creating the event.
+ * If the event has a self parent, this timestamp MUST be strictly greater than the `time_created` of the self parent. + */ + proto.Timestamp time_created = 3; + + /** + * A list of EventDescriptors representing the parents of this event.
+ * The list of parents SHALL include zero or one self parents, and zero or more other parents.
+ * The first element of the list SHALL be the self parent, if one exists.
+ * The list of parents SHALL NOT include more than one parent from the same creator. + */ + repeated EventDescriptor parents = 4; + + /** + * The event specification version.
+ * The specification described by this version SHALL encompass the format of the `GossipEvent` message, and also the + * format of all contained messages.
+ * This SHALL exactly match the specification version passed into the platform at construction. + */ + proto.SemanticVersion version = 17; // This field is temporary until birth_round migration is complete. Field number 17 chosen to avoid polluting cheaper 1 byte field numbers 1-16 +} diff --git a/sdk/src/main/proto/event_descriptor.proto b/sdk/src/main/proto/event_descriptor.proto new file mode 100644 index 000000000..bb5690da6 --- /dev/null +++ b/sdk/src/main/proto/event_descriptor.proto @@ -0,0 +1,80 @@ +/** + * # Event Descriptor + * Unique identifier for an event. + * + * Contains the hash of the event, the creator identifier, the birth round, and the generation. + * + * An event's descriptor is constructed individually by each node that receives a `GossipEvent`, + * to uniquely identify that event. An event's descriptor isn't part of the `GossipEvent` itself, + * since the descriptor contains the fields `hash` and `generation`, which can be computed locally. + * Nodes receiving a `GossipEvent` have the required information to construct the event descriptor + * immediately upon receiving the event, without needing to wait for the event to reach consensus. + * + * Aside from being a unique identifier for events that have been received through gossip, + * the event descriptor contains the necessary information to describe an event's parents, + * in the `parents` field of `GossipEvent`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119). + */ +syntax = "proto3"; + +package com.hedera.hapi.platform.event; + +/* + * Hedera Network Services Protobuf + * + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +option java_package = "com.hedera.hapi.platform.event.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * Unique identifier for an event. + */ +message EventDescriptor { + /** + * The hash of the event.
+ * The hash SHALL be a SHA-384 hash.
+ * The hash SHALL have the following inputs, in the specified order:
+ * 1. The bytes of the `EventCore` protobuf
+ * 2. The SHA-384 hash of each individual `EventTransaction`, in the order the transactions appear in the `event_transactions` field of the `GossipEvent` protobuf + */ + bytes hash = 1; + + /** + * The creator node identifier.
+ * This SHALL be the unique identifier for the node that created the event.
+ * This SHALL match the ID of the node as it appears in the address book. + */ + int64 creator_node_id = 2; + + /** + * The birth round of the event.
+ * The birth round SHALL be the pending consensus round at the time the event is created.
+ * The pending consensus round SHALL be **one greater** than the latest round to reach consensus. + */ + int64 birth_round = 3; + + /** + * The generation of the event.
+ * This value SHALL be **one greater** than the _maximum_ generation of all parents.
+ */ + int64 generation = 17; // This field is temporary until birth_round migration is complete. Field number 17 chosen to avoid polluting cheaper 1 byte field numbers 1-16 +} diff --git a/sdk/src/main/proto/event_transaction.proto b/sdk/src/main/proto/event_transaction.proto new file mode 100644 index 000000000..d43ce3b78 --- /dev/null +++ b/sdk/src/main/proto/event_transaction.proto @@ -0,0 +1,65 @@ +/** + * # Event Transaction + * An Event Transaction gossiped between nodes as part of events. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ +syntax = "proto3"; + +package com.hedera.hapi.platform.event; + +/* + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import "state_signature_transaction.proto"; + +option java_package = "com.hedera.hapi.platform.event.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * An Event Transaction gossiped between nodes as part of events. + * + * Each node MUST extract this transaction and process according to the type + * of transaction encoded.
+ * Both the platform and the application built on that platform MAY define event + * transactions.
+ * The encoded data MUST be a serialized protobuf message. + */ +message EventTransaction { + oneof transaction { + /** + * An application transaction. + *

+ * The contents of this transaction SHALL be defined by the application + * subsystem that created the event.
+ * The contents MUST be a serialized protobuf message. + */ + bytes application_transaction = 1; + /** + * A state signature. + *

+ * This transaction SHALL be a valid state signature for a state snapshot. + */ + StateSignatureTransaction state_signature_transaction = 2; + } + +} diff --git a/sdk/src/main/proto/exchange_rate.proto b/sdk/src/main/proto/exchange_rate.proto index 0531b2fb0..fd3c431f7 100644 --- a/sdk/src/main/proto/exchange_rate.proto +++ b/sdk/src/main/proto/exchange_rate.proto @@ -1,13 +1,26 @@ +/** + * # Exchange Rates + * Exchange rates that define ratios between HBAR and USD. + * + * Fees are denominated in USD, but paid in HBAR, so accurate exchange + * rates are important and the exchange rates kept in state are updated + * frequently.
+ * Exchange rates are also reported in every receipt for fee transparency. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,47 +32,73 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ + option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package 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 as a ratio of USD cents per HBAR. + * + * This ratio SHALL be used to convert tinycent (`10-8` USD cent) + * to tinybar for fees and other purposes.
+ * When applying an `ExchangeRate`, implementations SHOULD ensure input values + * are `tinycent` and/or `tinybar` before applying the exchange ratio.
+ * Exchange results MAY be converted to USD or HBAR via division if whole + * unit values are required. + * + * The ratio described here SHALL be assigned such that a value in `tinybar` + * may be obtained with the following equation. + * ``` + * amountInTinybar = (amountInTinycent * hbarEquiv) / centEquiv + * ``` */ message ExchangeRate { /** - * Denominator in calculation of exchange rate between hbar and cents + * Denominator for a ratio of USD cents per HBAR. */ int32 hbarEquiv = 1; /** - * Numerator in calculation of exchange rate between hbar and cents + * Numerator for a ratio of USD cents per HBAR. */ int32 centEquiv = 2; /** - * Expiration time in seconds for this exchange rate + * Expiration time stamp for this exchange rate. */ TimestampSeconds expirationTime = 3; } /** - * Two sets of exchange rates + * A set of two exchange rates.
+ * The exchange rate for the network is stored and reported as a set of + * two rates; current and next. This structure supports the network cleanly + * switching between exchange rates when necessary. This also provides clear + * notice to clients when the exchange rate will change and the exchange + * rate that will be applied for the next time period. + * + * The difference in rate between `currentRate` and `nextRate` MUST NOT exceed + * the configured maximum percentage change. This limit SHALL be a + * network configuration value. */ message ExchangeRateSet { /** - * Current exchange rate + * A current exchange rate. + *

+ * When present in a receipt, this SHALL be the exchange rate used to + * compute the fees for that transaction. */ ExchangeRate currentRate = 1; /** - * Next exchange rate which will take effect when current rate expires + * A future exchange rate. + *

+ * This exchange rate SHALL be applied after the current exchange + * rate expires. */ ExchangeRate nextRate = 2; } diff --git a/sdk/src/main/proto/file.proto b/sdk/src/main/proto/file.proto index eab958ace..234ea3b8e 100644 --- a/sdk/src/main/proto/file.proto +++ b/sdk/src/main/proto/file.proto @@ -1,13 +1,23 @@ +/** + * # File + * A "file" in the distributed ledger is a stream of bytes. These bytes may + * contain any data, and are limited in length based on network configuration + * (for example, 1048576). + * + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +29,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ import "basic_types.proto"; @@ -29,39 +38,79 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** - * Representation of a Hedera Token Service file in the network Merkle tree. + * Representation of an Hedera File Service `file`. * - * As with all network entities, a file has a unique entity number, which is given along - * with the network's shard and realm in the form of a shard.realm.number id. + * Files offer a place to store additional data, much more than is available in + * other entities, for use with smart contracts, non-fungible tokens, etc... + * As with all network entities, a file has a unique entity number, which is + * given along with the network's shard and realm in the form of a + * shard.realm.number id. */ message File { /** - * The file's unique file identifier in the Merkle state. + * This file's ID within the global network state. + *

+ * This value SHALL be unique within the network. */ FileID file_id = 1; + /** - * The file's consensus expiration time in seconds since the epoch. - */ + * The file's expiration time in seconds since the epoch.
+ * This value should be compared against consensus time, which may not + * exactly match clock time at the moment of expiration. + *

+ * For this purpose, `epoch` SHALL be the UNIX epoch with 0 at `1970-01-01T00:00:00.000Z`. + */ int64 expiration_second = 2; + /** - * All keys at the top level of a key list must sign to create, modify and delete the file. + * A list of keys that MUST sign any transaction to create + * or update this file. + *

+ * Only _one_ of these keys must sign a transaction to delete the file.
+ * This field MAY be `null` or an empty list.
+ * If this field is null or an empty `KeyList`, then the file SHALL be + * immutable.
+ * For an immutable file, the only transaction permitted to modify that + * file SHALL be a `fileUpdate` transaction with _only_ the + * `expirationTime` set. */ KeyList keys = 3; + /** - * The bytes that are the contents of the file + * The contents of the file. + *

+ * This SHALL be limited to the current maximum file size; typically no + * more than 1 Megabyte (1048576 bytes). */ bytes contents = 4; + /** - * The memo associated with the file (UTF-8 encoding max 100 bytes) + * A short description of the file. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 5; + /** - * Whether this file is deleted. + * A flag indicating that this file is deleted. + *

+ * The `contents` of a deleted "regular" file SHALL be an empty + * (zero length) bytes. */ bool deleted = 6; + /** - * The pre system delete expiration time in seconds - */ + * The pre-system-delete expiration time of a deleted "system" file, in seconds. + *

+ * This field SHALL contain the original expiration time of a "system" file + * that is deleted. This SHOULD be used to restore that expiration time if + * the file is subsequently "un-deleted" before it is purged from the + * system.
+ * A "regular" file cannot be "un-deleted", so this field SHALL NOT be set + * for those files. + */ int64 pre_system_delete_expiration_second = 7; } diff --git a/sdk/src/main/proto/file_append.proto b/sdk/src/main/proto/file_append.proto index 07c8f9d22..b459accf4 100644 --- a/sdk/src/main/proto/file_append.proto +++ b/sdk/src/main/proto/file_append.proto @@ -1,13 +1,21 @@ +/** + * # File Append + * A transaction body message to append data to a "file" in state. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,31 +27,60 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package 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. + * A transaction body for an `appendContent` transaction.
+ * This transaction body provides a mechanism to append content to a "file" in + * network state. Hedera transactions are limited in size, but there are many + * uses for in-state byte arrays (e.g. smart contract bytecode) which require + * more than may fit within a single transaction. The `appendFile` transaction + * exists to support these requirements. The typical pattern is to create a + * file, append more data until the full content is stored, verify the file is + * correct, then update the file entry with any final metadata changes (e.g. + * adding threshold keys and removing the initial upload key). + * + * Each append transaction MUST remain within the total transaction size limit + * for the network (typically 6144 bytes).
+ * The total size of a file MUST remain within the maximum file size limit for + * the network (typically 1048576 bytes). + * + * #### Signature Requirements + * Append transactions MUST have signatures from _all_ keys in the `KeyList` + * assigned to the `keys` field of the file.
+ * See the [File Service](#FileService) specification for a detailed + * explanation of the signature requirements for all file transactions. + * + * ### Block Stream Effects + * None */ message FileAppendTransactionBody { /** - * The file to which the bytes will be appended + * A file identifier.
+ * This identifies the file to which the `contents` will be appended. + *

+ * This field is REQUIRED.
+ * The identified file MUST exist.
+ * The identified file MUST NOT be larger than the current maximum file + * size limit.
+ * The identified file MUST NOT be deleted.
+ * The identified file MUST NOT be immutable. */ FileID fileID = 2; /** - * The bytes that will be appended to the end of the specified file + * An array of bytes to append.
+ *

+ * This content SHALL be appended to the identified file if this + * transaction succeeds.
+ * This field is REQUIRED.
+ * This field MUST NOT be empty. */ bytes contents = 4; } diff --git a/sdk/src/main/proto/file_create.proto b/sdk/src/main/proto/file_create.proto index bd768a180..45fc24bc6 100644 --- a/sdk/src/main/proto/file_create.proto +++ b/sdk/src/main/proto/file_create.proto @@ -1,13 +1,21 @@ +/** + * # File Create + * Messages to create a new file entry. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -30,75 +37,103 @@ 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. * - * 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. + * If successful, the new file SHALL contain the (possibly empty) content + * provided in the `contents` field.
+ * When the current consensus time exceeds the `expirationTime` value, the + * network SHALL expire the file, and MAY archive the state entry. * - * 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 the auto_renew_account field - * is set, the key of the referenced account must sign. + * #### Signature Requirements + * The HFS manages file authorization in a manner that can be confusing. + * The core element of file authorization is the `keys` field, + * which is a `KeyList`; a list of individual `Key` messages, each of which + * may represent a simple or complex key.
+ * The file service transactions treat this list differently.
+ * A `fileCreate`, `fileAppend`, or `fileUpdate` MUST have a valid signature + * from _each_ key in the list.
+ * A `fileDelete` MUST have a valid signature from _at least one_ key in + * the list. This is different, and allows a file "owned" by many entities + * to be deleted by any one of those entities. A deleted file cannot be + * restored, so it is important to consider this when assigning keys for + * a file.
+ * If any of the keys in a `KeyList` are complex, the full requirements of + * each complex key must be met to count as a "valid signature" for that key. + * A complex key structure (i.e. a `ThresholdKey`, or `KeyList`, possibly + * including additional `ThresholdKey` or `KeyList` descendants) may be + * assigned as the sole entry in a file `keys` field to ensure all transactions + * have the same signature requirements. * - * 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. + * If the `keys` field is an empty `KeyList`, then the file SHALL be immutable + * and the only transaction permitted to modify that file SHALL be a + * `fileUpdate` transaction with _only_ the `expirationTime` set. * - * 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. + * #### Shard and Realm + * The current API ignores shardID and realmID. All files are created in + * shard 0 and realm 0. Future versions of the API may 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. + * ### Block Stream Effects + * After the file is created, the FileID for it SHALL be returned in the + * transaction receipt, and SHALL be recorded in the transaction record. */ message FileCreateTransactionBody { /** - * The time at which this file should expire (unless FileUpdateTransaction is used before then - * to extend its life) + * An expiration timestamp. + *

+ * When the network consensus time exceeds this value, the network + * SHALL expire the file. */ Timestamp expirationTime = 2; /** - * 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. + * A list of keys that represent file "owners". + *

+ * Every `Key` in this list MUST sign this `fileCreate` transaction, as + * well as any `fileUpdate` or `fileAppend` that modifies this file.
+ * At least one `Key` in this list MUST sign any `fileDelete` transaction + * to delete this file.
+ * If this `KeyList` is empty, the file SHALL be created immutable and the + * only field that may be changed subsequently is the `expirationTime`. + * An immutable file cannot be deleted except with a `systemDelete` + * transaction, or by expiration. */ KeyList keys = 3; /** - * The bytes that are the contents of the file + * A byte array of file content. + *

+ * The file SHALL be created with initial content equal to this field. */ bytes contents = 4; /** - * Shard in which this file is created + * A shard in which this file is created */ ShardID shardID = 5; /** - * The Realm in which to the file is created (leave this null to create a new realm) + * A realm in which this file is created. + *

+ * The shard number for this realm MUST match the value in `shardID`.
+ * Currently, this MUST be `0` for both fields.
+ * If the desired realm is `0.0`, this SHOULD NOT be set. */ RealmID realmID = 6; /** - * If realmID is null, then this the admin key for the new realm that will be created + * The "create realm" was never enabled, and + * should not be possible on file creation.
+ * An admin key for a new realm, if one is created. + * Added deprecated tag 2024-05. */ - Key newRealmAdminKey = 7; + Key newRealmAdminKey = 7 [deprecated = true]; /** - * The memo associated with the file (UTF-8 encoding max 100 bytes) + * A short description of this file. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 8; } diff --git a/sdk/src/main/proto/file_delete.proto b/sdk/src/main/proto/file_delete.proto index f4b23c988..848153b7a 100644 --- a/sdk/src/main/proto/file_delete.proto +++ b/sdk/src/main/proto/file_delete.proto @@ -1,13 +1,21 @@ +/** + * # File Delete + * A message for a transaction to delete a file. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,16 +36,38 @@ 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. + * Mark a file as deleted and remove its content from network state. + * + * The metadata for a deleted file SHALL be retained at least until the + * expiration time for the file is exceeded.
+ * On completion, the identified file SHALL be marked `deleted`.
+ * On completion, the identified file SHALL have an empty `contents` array.
+ * This transaction SHALL be final and irreversible.
+ * + * #### Signature Requirements + * At least _one_ key from the `KeyList` in the `keys` field of the + * identified file MUST sign this transaction.
+ * If the keys field for the identified file is an empty `KeyList` (because that + * file was previously created or updated to have an empty `KeyList`), then the + * file is considered immutable and this message SHALL fail as UNAUTHORIZED. + * See the [File Service](#FileService) specification for a detailed + * explanation of the signature requirements for all file transactions. + * + * ### What is a "system" file + * A "system" file is any file with a file number less than or equal to the + * current configuration value for `ledger.numReservedSystemEntities`, + * typically `750`. + * + * ### Block Stream Effects + * None */ message FileDeleteTransactionBody { /** - * The file to delete. It will be marked as deleted until it expires. Then it will disappear. + * A file identifier.
+ * This identifies the file to delete. + *

+ * The identified file MUST NOT be a "system" file.
+ * This field is REQUIRED. */ FileID fileID = 2; } diff --git a/sdk/src/main/proto/file_get_contents.proto b/sdk/src/main/proto/file_get_contents.proto index ee888d6af..889ce2ddc 100644 --- a/sdk/src/main/proto/file_get_contents.proto +++ b/sdk/src/main/proto/file_get_contents.proto @@ -1,13 +1,22 @@ +/** + * # File Get Contents + * Messages for a query to retrieve the content of a file in the + * Hedera File Service (HFS). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,47 +39,68 @@ 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. + * A query request to the Hedera File Service (HFS) for file content.
+ * This query requests the content of a file, but none of the information + * _about_ a file. A client should submit a `fileGetInfo` query to view + * information about a file.
+ * File content may also be available from a block node or mirror node, + * generally at lower cost. */ message FileGetContentsQuery { /** - * 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 information sent with every query operation.
+ * This includes 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 + * A file identifier. + *

+ * This MUST be the identifier of a file that exists in HFS.
+ * This value SHALL identify the file to be queried. */ FileID fileID = 2; } /** - * Response when the client sends the node FileGetContentsQuery + * A response to a query for the content of a file in the + * Hedera File Service (HFS). + * + * This message SHALL contain the full content of the requested file, but + * SHALL NOT contain any metadata. */ message FileGetContentsResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; message FileContents { /** - * The file ID of the file whose contents are being returned + * A file identifier. + *

+ * This SHALL be the identifier of a file that exists in HFS.
+ * This value SHALL identify the file that was queried. */ FileID fileID = 1; /** - * The bytes contained in the file + * A byte array of file content. + *

+ * This SHALL contain the full content of the requested file.
+ * This SHALL be empty if, and only if, the file content is empty. */ bytes contents = 2; } /** - * the file ID and contents (a state proof can be generated for this) + * A combination of File identifier and content bytes. + *

+ * This SHALL NOT be set if the file does not exist.
+ * The network MAY generate a state proof for this field. */ FileContents fileContents = 2; } - - diff --git a/sdk/src/main/proto/file_get_info.proto b/sdk/src/main/proto/file_get_info.proto index 2d8f59978..a83774bd1 100644 --- a/sdk/src/main/proto/file_get_info.proto +++ b/sdk/src/main/proto/file_get_info.proto @@ -1,13 +1,24 @@ +/** + * # File Get Information + * Messages for a query to retrieve the metadata for a file in the + * Hedera File Service (HFS). + * + * The query defined here does not include the content of the file. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +30,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,75 +42,109 @@ 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. + * Query to request file metadata from the Hedera File Service (HFS).
+ * This query requests all of the information _about_ a file, but none of the + * _content_ of a file. A client should submit a `fileGetContents` query to + * view the content of a file. File content _may_ also be available from a + * block node or mirror node, generally at lower cost. + * + * File metadata SHALL be available for active files and deleted files.
+ * The size of a deleted file SHALL be `0` and the content SHALL be empty. */ message FileGetInfoQuery { /** - * 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 information sent with every query operation.
+ * This includes 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 + * A file identifier. + *

+ * This MUST be the identifier of a file that exists in HFS.
+ * This value SHALL identify the file to be queried. */ FileID fileID = 2; } /** - * Response when the client sends the node FileGetInfoQuery + * A response to a query for the metadata of a file in the HFS. */ message FileGetInfoResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; - message FileInfo { /** - * The file ID of the file for which information is requested + * A file identifier. + *

+ * This SHALL be the identifier of a file that exists in HFS.
+ * This value SHALL identify the file that was queried. */ FileID fileID = 1; /** - * Number of bytes in contents + * A size, in bytes, for the file. */ int64 size = 2; /** - * The current time at which this account is set to expire + * An expiration timestamp. + *

+ * The file SHALL NOT expire before the network consensus time + * exceeds this value.
+ * The file SHALL expire after the network consensus time + * exceeds this value.
*/ Timestamp expirationTime = 3; /** - * True if deleted but not yet expired + * A flag indicating this file is deleted. + *

+ * A deleted file SHALL have a size `0` and empty content. */ bool deleted = 4; /** - * One of these keys must sign in order to modify or delete the file + * A KeyList listing all keys that "own" the file. + *

+ * All keys in this list MUST sign a transaction to append to the + * file content, or to modify file metadata.
+ * At least _one_ key in this list MUST sign a transaction to delete + * this file.
+ * If this is an empty `KeyList`, the file is immutable, cannot be + * modified or deleted, but MAY expire. A `fileUpdate` transaction MAY + * extend the expiration time for an immutable file. */ KeyList keys = 5; /** - * The memo associated with the file + * A short description for this file. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 6; /** - * The ledger ID the response was returned from; please see HIP-198 for the network-specific IDs. + * A ledger identifier for the responding network. + *

+ * This value SHALL identify the distributed ledger that responded to + * this query. */ bytes ledger_id = 7; } /** - * The information about the file + * A combination of fields from the requested file metadata. + *

+ * This SHALL NOT be set if the identified file does not exist + * or has expired. */ FileInfo fileInfo = 2; } diff --git a/sdk/src/main/proto/file_service.proto b/sdk/src/main/proto/file_service.proto index cab4209ac..fa61eb0be 100644 --- a/sdk/src/main/proto/file_service.proto +++ b/sdk/src/main/proto/file_service.proto @@ -1,13 +1,26 @@ +/** + * # File Service + * gRPC definitions for the Hedera File Service (HFS). + * + * The HFS manages bulk data in the form of byte arrays of arbitrary + * size, up to a network-configured maximum size. These files are + * most often used to store bulk data for distributed applications + * and smart contracts. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,8 +32,8 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ + option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package @@ -30,46 +43,96 @@ import "transaction_response.proto"; import "transaction.proto"; /** - * Transactions and queries for the file service. + * Service gRPC definitions for the Hedera File Service (HFS). + * + * #### Signature Requirements + * The HFS manages file authorization differently, depending on type of file + * transaction, and this can be surprising.
+ * The core element of file authorization is the `keys` field, + * which is a `KeyList`; a list of individual `Key` messages, each of which + * may represent a simple or complex key.
+ * The file service transactions treat this list differently.
+ * A `fileCreate`, `fileAppend`, or `fileUpdate` MUST have a valid signature + * from _each_ key in the list.
+ * A `fileDelete` MUST have a valid signature from _at least one_ key in + * the list. This is different, and allows a file "owned" by many entities + * to be deleted by any one of those entities. A deleted file cannot be + * restored, so it is important to consider this when assigning keys for + * a file.
+ * If any of the keys in a `KeyList` are complex, the full requirements of + * each complex key must be met to count as a "valid signature" for that key. + * A complex key structure (i.e. a `ThresholdKey`, or `KeyList`, possibly + * including additional `ThresholdKey` or `KeyList` descendants) may be + * assigned as the sole entry in a file `keys` field to ensure all transactions + * have the same signature requirements. */ service FileService { /** - * Creates a file + * Create a file in HFS. */ rpc createFile (Transaction) returns (TransactionResponse); /** - * Updates a file + * Update a file in HFS. */ rpc updateFile (Transaction) returns (TransactionResponse); /** - * Deletes a file + * Delete a file in HFS.
+ * The content of a file deleted in this manner is completely removed + * from network state, but the file metadata remains. */ rpc deleteFile (Transaction) returns (TransactionResponse); /** - * Appends to a file + * Append content to a file in HFS. */ rpc appendContent (Transaction) returns (TransactionResponse); /** - * Retrieves the file contents + * Retrieve the content of a file in HFS.
+ * Note that this query retrieves _only_ the file content, not any of + * the metadata for the file. */ rpc getFileContent (Query) returns (Response); /** - * Retrieves the file information + * Retrieve the metadata for a file in HFS.
+ * Note that this query does not retrieve the file _content_. */ rpc getFileInfo (Query) returns (Response); /** - * Deletes a file if the submitting account has network admin privileges + * Delete a "regular" file without "owner" authorization.
+ * This transaction _does not_ require signatures for the keys in + * the file `keys` list, but must be signed by a "privileged" account. + *

+ * This transaction SHALL NOT accept a file identifier for + * a "system" file.
+ * This transaction SHALL NOT remove the _content_ of the file from state. + * This permits use of the `systemUndelete` to reverse this action if + * performed in error. + *

+ * This is a privileged transaction, and only accounts 2-59 are permitted + * to call this function, by default. The actual restriction is in the + * `api-permission.properties` file in the consensus node configuration. */ rpc systemDelete (Transaction) returns (TransactionResponse); /** - * Undeletes a file if the submitting account has network admin privileges + * Undelete a "regular" file. + * This transaction must be signed by a "privileged" account.
+ *

+ * This transaction SHALL NOT accept a file identifier for + * a "system" file.
+ * The file identified SHOULD have been previously deleted.
+ * This transaction SHALL NOT recover the _content_ of a file unless that + * file was deleted with a `systemDelete` transaction. The _content_ of a + * file deleted with a `fileDelete` transaction is not retained in state. + *

+ * This is a privileged transaction, and only accounts 2-60 are permitted + * to call this function, by default. The actual restriction is in the + * `api-permission.properties` file in the consensus node configuration. */ rpc systemUndelete (Transaction) returns (TransactionResponse); } diff --git a/sdk/src/main/proto/file_update.proto b/sdk/src/main/proto/file_update.proto index a7c595f69..db27449d8 100644 --- a/sdk/src/main/proto/file_update.proto +++ b/sdk/src/main/proto/file_update.proto @@ -1,13 +1,21 @@ +/** + * # File Update + * A message to modify the metadata for a file and/or _replace_ the contents. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,37 +38,73 @@ 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 If the update transaction sets the auto_renew_account_id field - * to anything other than the sentinel 0.0.0, the key of the referenced account must sign. + * Update the metadata, and/or replace the content, of a file in the + * Hedera File Service (HFS). + * + * Any field which is not set (i.e. is null) in this message, other than + * `fileID`, SHALL be ignored.
+ * If the `keys` list for the identified file is an empty `KeyList`, then + * this message MUST NOT set any field except `expirationTime`. + * + * #### Signature Requirements + * Every `Key` in the `keys` list for the identified file MUST sign this + * transaction, if any field other than `expirationTime` is to be updated.
+ * If the `keys` list for the identified file is an empty `KeyList` (because + * this file was previously created or updated to have an empty `KeyList`), + * then the file is considered immutable and this message MUST NOT set any + * field except `expirationTime`.
+ * See the [File Service](#FileService) specification for a detailed + * explanation of the signature requirements for all file transactions. + * + * ### Block Stream Effects + * None */ message FileUpdateTransactionBody { /** - * The ID of the file to update + * A file identifier for the file to update. + *

+ * This field is REQUIRED. */ FileID fileID = 1; /** - * The new expiry time (ignored if not later than the current expiry) + * An expiration timestamp. + *

+ * If set, this value MUST be strictly later than the existing + * `expirationTime` value, or else it will be ignored.
+ * If set, this value SHALL replace the existing `expirationTime`.
+ * If this field is the only field set, then this transaction SHALL NOT + * require any signature other than the `payer` for the transaction.
+ * When the network consensus time exceeds the then-current + * `expirationTime`, the network SHALL expire the file. */ Timestamp expirationTime = 2; /** - * The new list of keys that can modify or delete the file + * The new list of keys that "own" this file. + *

+ * If set, every key in this `KeyList` MUST sign this transaction.
+ * If set, every key in the _previous_ `KeyList` MUST _also_ + * sign this transaction.
+ * If this value is an empty `KeyList`, then the file SHALL be immutable + * after completion of this transaction. */ KeyList keys = 3; /** - * The new contents that should overwrite the file's current contents + * An array of bytes. + *

+ * This value, if set, SHALL _replace_ the existing file content. + * If this value is set to an empty byte array, the content of the file + * SHALL be unchanged. */ bytes contents = 4; /** - * If set, the new memo to be associated with the file (UTF-8 encoding max 100 bytes) + * A short description of this file. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ google.protobuf.StringValue memo = 5; } diff --git a/sdk/src/main/proto/freeze.proto b/sdk/src/main/proto/freeze.proto index a466b4181..6aa45a5b8 100644 --- a/sdk/src/main/proto/freeze.proto +++ b/sdk/src/main/proto/freeze.proto @@ -1,13 +1,21 @@ +/** + * # Freeze + * Transaction body for a network "freeze" transaction. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,52 +38,115 @@ import "basic_types.proto"; import "freeze_type.proto"; /** - * At consensus, sets the consensus time at which the platform should stop creating events and - * accepting transactions, and enter a maintenance window. + * A transaction body for all five freeze transactions. + * + * Combining five different transactions into a single message, this + * transaction body MUST support options to schedule a freeze, abort a + * scheduled freeze, prepare a software upgrade, prepare a telemetry + * upgrade, or initiate a software upgrade. + * + * For a scheduled freeze, at the scheduled time, according to + * network consensus time + * - A freeze (`FREEZE_ONLY`) causes the network nodes to stop creating + * events or accepting transactions, and enter a persistent + * maintenance state. + * - A freeze upgrade (`FREEZE_UPGRADE`) causes the network nodes to stop + * creating events or accepting transactions, and upgrade the node software + * from a previously prepared upgrade package. The network nodes then + * restart and rejoin the network after upgrading. + * + * For other freeze types, immediately upon processing the freeze transaction + * - A Freeze Abort (`FREEZE_ABORT`) cancels any pending scheduled freeze. + * - A prepare upgrade (`PREPARE_UPGRADE`) begins to extract the contents of + * the specified upgrade file to the local filesystem. + * - A telemetry upgrade (`TELEMETRY_UPGRADE`) causes the network nodes to + * extract a telemetry upgrade package to the local filesystem and signal + * other software on the machine to upgrade, without impacting the node or + * network processing. + * + * ### Block Stream Effects + * Unknown */ message FreezeTransactionBody { /** - * !! DEPRECATED and REJECTED by nodes + * Rejected if set; replace with `start_time`.
* The start hour (in UTC time), a value between 0 and 23 */ - int32 startHour = 1 [deprecated=true]; + int32 startHour = 1 [deprecated = true]; /** - * !! DEPRECATED and REJECTED by nodes + * Rejected if set; replace with `start_time`.
* The start minute (in UTC time), a value between 0 and 59 */ - int32 startMin = 2 [deprecated=true]; + int32 startMin = 2 [deprecated = true]; /** - * !! DEPRECATED and REJECTED by nodes + * Rejected if set; end time is neither assigned nor guaranteed and depends + * on many uncontrolled factors.
* The end hour (in UTC time), a value between 0 and 23 */ - int32 endHour = 3 [deprecated=true]; + int32 endHour = 3 [deprecated = true]; /** - * !! DEPRECATED and REJECTED by nodes + * Rejected if set; end time is neither assigned nor guaranteed and depends + * on many uncontrolled factors.
* The end minute (in UTC time), a value between 0 and 59 */ - int32 endMin = 4 [deprecated=true]; + int32 endMin = 4 [deprecated = true]; /** - * If set, the file whose contents should be used for a network software update during the - * maintenance window. + * An upgrade file. + *

+ * If set, the identifier of a file in network state.
+ * The contents of this file MUST be a `zip` file and this data + * SHALL be extracted to the node filesystem during a + * `PREPARE_UPGRADE` or `TELEMETRY_UPGRADE` freeze type.
+ * The `file_hash` field MUST match the SHA384 hash of the content + * of this file.
+ * The extracted data SHALL be used to perform a network software update + * if a `FREEZE_UPGRADE` freeze type is subsequently processed. */ FileID update_file = 5; /** - * If set, the expected hash of the contents of the update file (used to verify the update). + * A SHA384 hash of file content.
+ * This is a hash of the file identified by `update_file`. + *

+ * This MUST be set if `update_file` is set, and MUST match the + * SHA384 hash of the contents of that file. */ bytes file_hash = 6; /** - * The consensus time at which the maintenance window should begin. + * A start time for the freeze. + *

+ * If this field is REQUIRED for the specified `freeze_type`, then + * when the network consensus time reaches this instant

    + *
  1. The network SHALL stop accepting transactions.
    2. + *
  2. The network SHALL gossip a freeze state.
    3. + *
  3. The nodes SHALL, in coordinated order, disconnect and + * shut down.
    4. + *
  4. The nodes SHALL halt or perform a software upgrade, depending + * on `freeze_type`.
    5. + *
  5. If the `freeze_type` is `FREEZE_UPGRADE`, the nodes SHALL + * restart and rejoin the network upon completion of the + * software upgrade.
    6. + *
+ *
+ * If the `freeze_type` is `TELEMETRY_UPGRADE`, the start time is required, + * but the network SHALL NOT stop, halt, or interrupt transaction + * processing. The required field is an historical anomaly and SHOULD + * change in a future release.
*/ Timestamp start_time = 7; /** - * The type of network freeze or upgrade operation to perform. + * The type of freeze. + *

+ * This REQUIRED field effectively selects between five quite different + * transactions in the same transaction body. Depending on this value + * the service may schedule a freeze, prepare upgrades, perform upgrades, + * or even abort a previously scheduled freeze. */ FreezeType freeze_type = 8; } diff --git a/sdk/src/main/proto/freeze_service.proto b/sdk/src/main/proto/freeze_service.proto index b43d1f8de..35313441c 100644 --- a/sdk/src/main/proto/freeze_service.proto +++ b/sdk/src/main/proto/freeze_service.proto @@ -1,13 +1,21 @@ +/** + * # Freeze Service + * A service to manage network freeze events. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,8 +27,8 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ + option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package @@ -28,12 +36,22 @@ import "transaction_response.proto"; import "transaction.proto"; /** - * The request and responses for freeze service. + * A service to manage network "freeze" events. + * + * This service provides a facility to prepare for network upgrades, halt network processing, + * perform network software upgrades, and automatically restart the network following an upgrade. */ service FreezeService { /** - * Freezes the nodes by submitting the transaction. The grpc server returns the - * TransactionResponse + * Freeze, cancel, or prepare a freeze. + * This single transaction performs all of the functions supported + * by the network freeze service. These functions include actions to + * prepare an upgrade, prepare a telemetry upgrade, freeze the network, + * freeze the network for upgrade, or abort a scheduled freeze. + *

+ * The actual freeze action SHALL be determined by the `freeze_type` field + * of the `FreezeTransactionBody`.
+ * The transaction body MUST be a `FreezeTransactionBody`. */ rpc freeze (Transaction) returns (TransactionResponse); } diff --git a/sdk/src/main/proto/freeze_type.proto b/sdk/src/main/proto/freeze_type.proto index c18c5e109..1f5628856 100644 --- a/sdk/src/main/proto/freeze_type.proto +++ b/sdk/src/main/proto/freeze_type.proto @@ -1,13 +1,21 @@ +/** + * # Freeze Type + * An enumeration to select the type of a network freeze. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,45 +34,103 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** -* The type of network freeze or upgrade operation to be performed. This type dictates which -* fields are required. -*/ + * An enumeration of possible network freeze types. + * + * Each enumerated value SHALL be associated to a single network freeze + * scenario. Each freeze scenario defines the specific parameters + * REQUIRED for that freeze. + */ enum FreezeType { /** - * An (invalid) default value for this enum, to ensure the client explicitly sets - * the intended type of freeze transaction. + * An invalid freeze type. + *

+ * The first value in a protobuf enum is a default value. This default + * is RECOMMENDED to be an invalid value to aid in detecting unset fields. */ UNKNOWN_FREEZE_TYPE = 0; /** - * Freezes the network at the specified time. The start_time field must be provided and - * must reference a future time. Any values specified for the update_file and file_hash - * fields will be ignored. This transaction does not perform any network changes or - * upgrades and requires manual intervention to restart the network. + * Freeze the network, and take no further action. + *

+ * The `start_time` field is REQUIRED, MUST be strictly later than the + * consensus time when this transaction is handled, and SHOULD be between + * `300` and `3600` seconds after the transaction identifier + * `transactionValidStart` field.
+ * The fields `update_file` and `file_hash` SHALL be ignored.
+ * A `FREEZE_ONLY` transaction SHALL NOT perform any network + * changes or upgrades.
+ * After this freeze is processed manual intervention is REQUIRED + * to restart the network. */ FREEZE_ONLY = 1; /** - * A non-freezing operation that initiates network wide preparation in advance of a - * scheduled freeze upgrade. The update_file and file_hash fields must be provided and - * valid. The start_time field may be omitted and any value present will be ignored. + * This freeze type does not freeze the network, but begins + * "preparation" to upgrade the network. + *

+ * The fields `update_file` and `file_hash` are REQUIRED + * and MUST be valid.
+ * The `start_time` field SHALL be ignored.
+ * A `PREPARE_UPGRADE` transaction SHALL NOT freeze the network or + * interfere with general transaction processing.
+ * If this freeze type is initiated after a `TELEMETRY_UPGRADE`, the + * prepared telemetry upgrade SHALL be reset and all telemetry upgrade + * artifacts in the filesystem SHALL be deleted.
+ * At some point after this freeze type completes (dependent on the size + * of the upgrade file), the network SHALL be prepared to complete + * a software upgrade of all nodes. */ PREPARE_UPGRADE = 2; /** - * Freezes the network at the specified time and performs the previously prepared - * automatic upgrade across the entire network. + * Freeze the network to perform a software upgrade. + *

+ * The `start_time` field is REQUIRED, MUST be strictly later than the + * consensus time when this transaction is handled, and SHOULD be between + * `300` and `3600` seconds after the transaction identifier + * `transactionValidStart` field.
+ * A software upgrade file MUST be prepared prior to this transaction.
+ * After this transaction completes, the network SHALL initiate an + * upgrade and restart of all nodes at the start time specified. */ FREEZE_UPGRADE = 3; /** - * Aborts a pending network freeze operation. + * Abort a pending network freeze operation. + *

+ * All fields SHALL be ignored for this freeze type.
+ * This freeze type MAY be submitted after a `FREEZE_ONLY`, + * `FREEZE_UPGRADE`, or `TELEMETRY_UPGRADE` is initiated.
+ * This freeze type MUST be submitted and reach consensus + * before the `start_time` designated for the current pending + * freeze to be effective.
+ * After this freeze type is processed, the upgrade file hash + * and pending freeze start time stored in the network SHALL + * be reset to default (empty) values. */ FREEZE_ABORT = 4; /** - * Performs an immediate upgrade on auxilary services and containers providing - * telemetry/metrics. Does not impact network operations. + * Prepare an upgrade of auxiliary services and containers + * providing telemetry/metrics. + *

+ * The `start_time` field is REQUIRED, MUST be strictly later than the + * consensus time when this transaction is handled, and SHOULD be between + * `300` and `3600` seconds after the transaction identifier + * `transactionValidStart` field.
+ * The `update_file` field is REQUIRED and MUST be valid.
+ * A `TELEMETRY_UPGRADE` transaction SHALL NOT freeze the network or + * interfere with general transaction processing.
+ * This freeze type MUST NOT be initiated between a `PREPARE_UPGRADE` + * and `FREEZE_UPGRADE`. If this freeze type is initiated after a + * `PREPARE_UPGRADE`, the prepared upgrade SHALL be reset and all software + * upgrade artifacts in the filesystem SHALL be deleted.
+ * At some point after this freeze type completes (dependent on the + * size of the upgrade file), the network SHALL automatically upgrade + * the telemetry/metrics services and containers as directed in + * the specified telemetry upgrade file. + *

The condition that `start_time` is REQUIRED is an + * historical anomaly and SHOULD change in a future release.
*/ TELEMETRY_UPGRADE = 5; } diff --git a/sdk/src/main/proto/get_account_details.proto b/sdk/src/main/proto/get_account_details.proto index 98ebe7f27..f08a4b15a 100644 --- a/sdk/src/main/proto/get_account_details.proto +++ b/sdk/src/main/proto/get_account_details.proto @@ -1,13 +1,21 @@ +/** + * # Get Account Details + * A standard query to inspect the full detail of an account. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2022 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,195 +38,388 @@ import "duration.proto"; import "basic_types.proto"; import "query_header.proto"; import "response_header.proto"; -import "crypto_add_live_hash.proto"; -import "google/protobuf/wrappers.proto"; /** - * Gets all the information about an account, including balance and allowances. This does not get the list of - * account records. + * Request detail information about an account. + * + * The returned information SHALL include balance and allowances.
+ * The returned information SHALL NOT include a list of account records. + * + * #### Important + * This query is a _privileged_ query. Only "system" accounts SHALL be + * permitted to submit this query. */ message GetAccountDetailsQuery { /** - * Account details sent from client to node, including the signed payment, and what kind of - * response is requested (cost, state proof, both, or neither). + * Standard information sent with every query operation.
+ * This includes 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 + * An account ID for which information is requested + *

+ * This value SHALL identify the account to be queried.
+ * This value MUST identify a valid account.
+ * This field is REQUIRED. */ AccountID account_id = 2; } /** - * Response when the client sends the node GetAccountDetailsQuery + * A response to a `GetAccountDetailsQuery`. + * + * This SHALL contain the account details if requested and successful. */ message GetAccountDetailsResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; + /** + * Information describing a single Account in the Hedera distributed ledger. + * + * #### Attributes + * Each Account may have a unique three-part identifier, a Key, and one or + * more token balances. Accounts also have an alias, which has multiple + * forms, and may be set automatically. Several additional items are + * associated with the Account to enable full functionality. + * + * #### Expiration + * Accounts, as most items in the network, have an expiration time, recorded + * as a `Timestamp`, and must be "renewed" for a small fee at expiration. + * This helps to reduce the amount of inactive accounts retained in state. + * Another account may be designated to pay any renewal fees and + * automatically renew the account for (by default) 30-90 days at a time as + * a means to optionally ensure important accounts remain active. + * + * ### Staking + * Accounts may participate in securing the network by "staking" the account + * balances to a particular network node, and receive a portion of network + * fees as a reward. An account may optionally decline these rewards but + * still stake its balances. + * + * #### Transfer Restrictions + * An account may optionally require that inbound transfer transactions be + * signed by that account as receiver (in addition to any other signatures + * required, including sender). + * + */ message AccountDetails { /** - * The account ID for which this information applies + * The unique ID of this account. + *

+ * An account ID, when assigned to this field, SHALL be of + * the form `shard.realm.number`.
+ * Transactions MAY reference the account by alias, but the account + * itself MUST always have a purely numeric identifier. This numeric + * ID is the value used to reference the account in query responses, + * transaction receipts, transaction records, and the block stream. */ AccountID account_id = 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 + * A Solidity ID.
+ * This identifies the contract instance, and the `Account` associated + * with that contract instance. + *

+ * This SHALL be populated if this account is a smart contract, and + * SHALL NOT be populated otherwise.
+ * This SHALL be formatted as a string according to Solidity ID + * standards. */ string contract_account_id = 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 + * A boolean indicating that this account is deleted. */ bool deleted = 3; /** - * [Deprecated] 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. + * Replaced by StakingInfo.
+ * ID of the account to which this account is staking its balances. If + * this account is not currently staking its balances, then this field, + * if set, SHALL be the sentinel value of `0.0.0`. */ AccountID proxy_account_id = 4 [deprecated = true]; /** - * The total number of tinybars proxy staked to this account + * The total amount of tinybar proxy staked to this account. */ int64 proxy_received = 5; /** - * 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. + * The key to be used to sign transactions from this account, if any. + *

+ * This key SHALL NOT be set for hollow accounts until the account + * is finalized.
+ * This key SHALL be set on all other accounts, except for certain + * immutable accounts (0.0.800 and 0.0.801) necessary for network + * function and otherwise secured by the governing council. */ Key key = 6; /** - * The current balance of account in tinybars + * The HBAR balance of this account, in tinybar (10-8 HBAR). + *

+ * This value SHALL always be a whole number. */ uint64 balance = 7; /** - * If true, no transaction can transfer to this account unless signed by this account's key + * A boolean indicating that the account requires a receiver signature + * for inbound token transfer transactions. + *

+ * If this value is `true` then a transaction to transfer tokens to this + * account SHALL NOT succeed unless this account has signed the + * transfer transaction. */ bool receiver_sig_required = 8; /** - * The TimeStamp time at which this account is set to expire + * The current expiration time for this account. + *

+ * This account SHALL be due standard renewal fees when the network + * consensus time exceeds this time.
+ * If rent and expiration are enabled for the network, and automatic + * renewal is enabled for this account, renewal fees SHALL be charged + * after this time, and, if charged, the expiration time SHALL be + * extended for another renewal period.
+ * This account MAY be expired and removed from state at any point + * after this time if not renewed.
+ * An account holder MAY extend this time by submitting an account + * update transaction to modify expiration time, subject to the current + * maximum expiration time for the network. */ Timestamp expiration_time = 9; /** - * 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. + * A duration to extend this account's expiration. + *

+ * The network SHALL extend the account's expiration by this + * duration, if funds are available, upon automatic renewal.
+ * This SHALL NOT apply if the account is already deleted + * upon expiration.
+ * If this is not provided in an allowed range on account creation, the + * transaction SHALL fail with INVALID_AUTO_RENEWAL_PERIOD. The default + * values for the minimum period and maximum period are currently + * 30 days and 90 days, respectively. */ Duration auto_renew_period = 10; /** - * All tokens related to this account + * As of `HIP-367`, which enabled unlimited token associations, the + * potential scale for this value requires that users consult a mirror + * node for this information. Only the top `maxRelsPerInfoQuery` + * (default 1000) relationships will be returned by this query.
+ * A list of tokens to which this account is "associated", enabling the + * transfer of that token type by this account. */ repeated TokenRelationship token_relationships = 11; /** - * The memo associated with the account + * A short description of this account. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 12; /** - * The number of NFTs owned by this account + * The total number of non-fungible/unique tokens owned by this account. */ int64 owned_nfts = 13; /** - * The maximum number of tokens that an Account can be implicitly associated with. + * The maximum number of tokens that can be auto-associated with the + * account. + *

+ * If this is less than or equal to `used_auto_associations` (or 0), + * then this account MUST manually associate with a token before + * transacting in that token.
+ * Following HIP-904 This value may also be `-1` to indicate no + * limit.
+ * This value MUST NOT be less than `-1`. */ int32 max_automatic_token_associations = 14; /** - * The alias of this account + * An account EVM alias.
+ * This is a value used in some contexts to reference an account when + * the tripartite account identifier is not available. + *

+ * This field, when set to a non-default value, is immutable and + * SHALL NOT be changed. */ bytes alias = 15; /** - * The ledger ID the response was returned from; please see HIP-198 for the network-specific IDs. + * The ledger ID of the network that generated this response. + *

+ * This value SHALL identify the distributed ledger that responded to + * this query. */ bytes ledger_id = 16; /** - * All of the hbar allowances approved by the account owner. + * A list of crypto (HBAR) allowances approved by this account. + *

+ * If this is not empty, each allowance SHALL permit a specified + * "spender" account to spend this account's HBAR balance, up + * to a designated limit.
+ * This field SHALL permit spending only HBAR balance, not other + * tokens the account may hold.
+ * Allowances for other tokens SHALL be listed in the + * `token_allowances` field or the + * `approve_for_all_nft_allowances` field. */ repeated GrantedCryptoAllowance granted_crypto_allowances = 17; /** - * All of the non-fungible token allowances approved by the account owner. + * A list of non-fungible token (NFT) allowances approved by + * this account. + *

+ * If this is not empty, each allowance SHALL permit a specified + * "spender" account to transfer _all_ of this account's + * non-fungible/unique tokens from a particular collection.
+ * Allowances for a specific serial number MUST be directly + * associated with that specific non-fungible/unique token, rather + * than the holding account. */ repeated GrantedNftAllowance granted_nft_allowances = 18; /** - * All of the fungible token allowances approved by the account owner. + * A list of fungible token allowances approved by this account. + *

+ * If this is not empty, each allowance SHALL permit a specified + * "spender" to spend this account's fungible tokens, of the + * designated type, up to a designated limit. */ repeated GrantedTokenAllowance granted_token_allowances = 19; } + /** - * Details of the account (a state proof can be generated for this) + * Details of the account. + *

+ * A state proof MAY be generated for this field. */ AccountDetails account_details = 2; } /** - * A granted allowance of hbar transfers for a spender relative to the owner account. + * Permission granted by one account (the "funding" account) to another + * account (the "spender" account) that allows the spender to spend a + * specified amount of HBAR owned by the funding account. + * + * An allowance SHALL NOT transfer any HBAR directly, it only permits + * transactions signed only by the spender account to transfer HBAR, up + * to the amount specified, from the funding account. + * + * Once the specified amount is spent, the allowance SHALL be consumed + * and a new allowance SHALL be required before that spending account + * may spend additional HBAR from the funding account. */ message GrantedCryptoAllowance { /** - * The account ID of the spender of the hbar allowance. + * The identifier for the spending account associated with this allowance. + *

+ * This account SHALL be permitted to sign transactions to spend + * HBAR from the funding/allowing account.
+ * This permission SHALL be limited to no more than the specified `amount`. */ AccountID spender = 1; /** - * The amount of the spender's allowance in tinybars. + * The maximum amount that the spender account may transfer within + * the scope of this allowance. + *

+ * This allowance SHALL be consumed if any combination of transfers + * authorized via this allowance meet this value in total.
+ * This value MUST be specified in tinybar (i.e. 10-8 HBAR). */ int64 amount = 2; } /** - * A granted allowance for all the NFTs of a token for a spender relative to the owner account. + * Permission granted by one account (the "funding" account) to another + * account (the "spender" account) that allows the spender to transfer + * all serial numbers of a specific non-fungible/unique token (NFT) + * collection owned by the funding account.
+ * This is a broad permission, as it does not matter how many NFTs of the + * specified collection the funding account owns, the spender MAY dispose + * of any or all of them with this allowance.
+ * Each token type (typically a collection of NFTs) SHALL require + * a separate allowance.
+ * Allowances for a specific serial number MUST be directly associated + * with that specific non-fungible/unique token, rather than + * the holding account. + * + * An allowance SHALL NOT transfer any tokens directly, it only permits + * transactions signed only by the spender account to transfer any + * non-fungible/unique tokens of the specified type owned by + * the funding account. */ message GrantedNftAllowance { /** - * The token that the allowance pertains to. + * The identifier for the token associated with this allowance. + *

+ * This token MUST be a non-fungible/unique token. */ TokenID token_id = 1; /** - * The account ID of the spender that has been granted access to all NFTs of the owner + * The identifier for the spending account associated with this allowance. + *

+ * This account SHALL be permitted to sign transactions to spend + * tokens of the associated token type from the funding/allowing account. */ AccountID spender = 2; } /** - * A granted allowance of fungible token transfers for a spender relative to the owner account. + * Permission granted by one account (the "funding" account) to another + * account (the "spender" account) that allows the spender to spend a + * specified amount of a specific non-HBAR fungible token from the + * balance owned by the funding account. + * + * An allowance SHALL NOT transfer any tokens directly, it only permits + * transactions signed only by the spender account to transfer tokens + * of the specified type, up to the amount specified, from the funding account. + * + * Once the specified amount is spent, the allowance SHALL be consumed + * and a new allowance SHALL be required before that spending account + * may spend additional tokens from the funding account. */ message GrantedTokenAllowance { /** - * The token that the allowance pertains to. + * The identifier for the token associated with this allowance. + *

+ * This token MUST be a fungible/common token. */ TokenID token_id = 1; /** - * The account ID of the token allowance spender. + * The identifier for the spending account associated with this allowance. + *

+ * This account SHALL be permitted to sign transactions to spend tokens + * of the associated token type from the funding/allowing account.
+ * This permission SHALL be limited to no more than the specified `amount`. */ AccountID spender = 2; - /** - * The amount of the spender's token allowance. + /* + * The maximum amount that the spender account may transfer within + * the scope of this allowance. + *

+ * This allowance SHALL be consumed if any combination of transfers + * authorized via this allowance meet this value in total.
+ * This value MUST be specified in the smallest units of the relevant + * token (i.e. 10-decimals whole tokens). */ int64 amount = 3; } - diff --git a/sdk/src/main/proto/get_by_key.proto b/sdk/src/main/proto/get_by_key.proto index e166b3367..2d5773d40 100644 --- a/sdk/src/main/proto/get_by_key.proto +++ b/sdk/src/main/proto/get_by_key.proto @@ -1,13 +1,33 @@ +/** + * # Get By Key + * An obsolete query to obtain a list of entities that refer to + * a given Key object.
+ * Returned entities may be accounts, files, smart contracts, and/or + * live hash entries. + * + * > Important + * >> This query is obsolete and not supported.
+ * >> Any query of this type that is submitted SHALL fail with a `PRE_CHECK` + * >> result of `NOT_SUPPORTED`. + * + * > Implementation Note + * >> This query is not defined for any service, and while it is implemented + * >> in the "Network Admin" service, it may be unnecessary to do so. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +39,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,27 +51,36 @@ 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. + * Query all accounts, claims, files, and smart contract instances whose + * associated keys include the given Key. + * + * > This query is no longer supported. */ message GetByKeyQuery { + option deprecated = true; + /** - * 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 information sent with every query operation.
+ * This includes 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. + * The key to search for. It MUST NOT contain a contractID nor + * a ThresholdKey. */ 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) + * + * > The query that defines this message is no longer supported. */ message EntityID { + option deprecated = true; + oneof entity { /** * The Account ID for the cryptocurrency account @@ -60,7 +88,7 @@ message EntityID { AccountID accountID = 1; /** - * A uniquely identifying livehash of an acount + * A uniquely identifying livehash of an account */ LiveHash liveHash = 2; @@ -79,16 +107,22 @@ message EntityID { /** * Response when the client sends the node GetByKeyQuery + * + * > This query is no longer supported. */ message GetByKeyResponse { + option deprecated = true; + /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * The list of entities that include this public key in their associated Key list + * The list of entities that include this public key in their + * associated Key list */ repeated EntityID entities = 2; } diff --git a/sdk/src/main/proto/get_by_solidity_id.proto b/sdk/src/main/proto/get_by_solidity_id.proto index 1c9d111c3..f2a8b36fc 100644 --- a/sdk/src/main/proto/get_by_solidity_id.proto +++ b/sdk/src/main/proto/get_by_solidity_id.proto @@ -1,13 +1,27 @@ +/** + * # Get By Solidity + * A standard query to obtain account and contract identifiers for a smart + * contract, given the Solidity identifier for that contract. + * + * > Important + * >> This query is obsolete and not supported.
+ * >> Any query of this type that is submitted SHALL fail with a `PRE_CHECK` + * >> result of `NOT_SUPPORTED`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +33,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,46 +44,60 @@ 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. + * Query to read Contract, Account, and File identifiers for a smart + * contract given a Solidity identifier. */ message GetBySolidityIDQuery { + option deprecated = true; /** - * 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 information sent with every query operation.
+ * This includes 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 + * A contract ID in the format used by Solidity. + *

+ * This field is REQUIRED. */ string solidityID = 2; } /** - * Response when the client sends the node GetBySolidityIDQuery + * Response to a getBySolidityId query. + * + * This message returns the account, contract, and file identifiers for + * a smart contract. */ message GetBySolidityIDResponse { + option deprecated = true; /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * The Account ID for the cryptocurrency account + * An account identifier. + *

+ * This SHALL identify an account that backs the requested smart contract. */ AccountID accountID = 2; /** - * The file Id for the file + * A file identifier. + *

+ * This SHALL identify a file, the contents of which are the EVM + * bytecode for the requested smart contract. */ FileID fileID = 3; /** - * A smart contract ID for the instance (if this is included, then the associated accountID will - * also be included) + * A contract identifier. + *

+ * This SHALL identify the requested smart contract. */ ContractID contractID = 4; } diff --git a/sdk/src/main/proto/gossip_event.proto b/sdk/src/main/proto/gossip_event.proto new file mode 100644 index 000000000..0752790ae --- /dev/null +++ b/sdk/src/main/proto/gossip_event.proto @@ -0,0 +1,81 @@ +/** + * # Gossip Event + * An event that is sent and received via gossip + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119). + */ +syntax = "proto3"; + +package com.hedera.hapi.platform.event; + +/* + * Hedera Network Services Protobuf + * + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import "event_transaction.proto"; +import "event_core.proto"; + +option java_package = "com.hedera.hapi.platform.event.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * An event that is sent and received via gossip + */ +message GossipEvent { + /** + * The core event data + */ + EventCore event_core = 1; + + /** + * A node signature on the event hash.
+ * The signature SHALL be created with the SHA384withRSA algorithm.
+ * The signature MUST verify using the public key belonging to the `event_creator`.
+ * The `event_creator` public key SHALL be read from the address book that corresponds to the event's birth round.
+ * The signed event hash SHALL be a SHA-384 hash.
+ * The signed event hash SHALL have the following inputs, in the specified order:
+ * 1. The bytes of the `event_core` field
+ * 2. The SHA-384 hash of each individual `EventTransaction`, in the order the transaction appear in the `event_transaction` field + */ + bytes signature = 2; + + /** + * The event transaction. + *

+ * This field MAY contain zero transactions.
+ * This field MUST NOT exceed `maxTransactionCountPerEvent` entries, initially `245760`.
+ * This total size of this field MUST NOT exceed `maxTransactionBytesPerEvent`, initially `245760` bytes.
+ * Deprecated in favor of the `transaction` field. The idea is to clean the design of event transactions.
+ * This is transitional state until 'transaction' field is fully adopted. + */ + repeated EventTransaction event_transaction = 3 [deprecated = true]; + + /** + * A list of serialized transactions. + *

+ * This field MAY contain zero transactions.
+ * Each transaction in this list SHALL be presented exactly as + * it was supplied to the consensus algorithm.
+ * This field MUST contain one entry for each transaction + * included in this gossip event. + */ + repeated bytes transactions = 4; +} diff --git a/sdk/src/main/proto/hints_types.proto b/sdk/src/main/proto/hints_types.proto new file mode 100644 index 000000000..8385cd6f4 --- /dev/null +++ b/sdk/src/main/proto/hints_types.proto @@ -0,0 +1,182 @@ +syntax = "proto3"; + +package com.hedera.hapi.node.state.hints; + +/* + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import "timestamp.proto"; + +option java_package = "com.hedera.hashgraph.sdk.proto"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * The id of a party in a hinTS scheme with a certain + * number of parties. + */ +message HintsPartyId { + /** + * The party id, in the range [0, num_parties). + */ + uint32 party_id = 1; + /** + * The number of parties in the hinTS scheme. + */ + uint32 num_parties = 2; +} + +/** + * A set of hinTS keys submitted by a node. + */ +message HintsKeySet { + /** + * The id of the node submitting these keys. + */ + uint64 node_id = 1; + /** + * The consensus time at which the network adopted the active + * hinTS key in this set. + */ + proto.Timestamp adoption_time = 2; + /** + * The party's active hinTS key. + */ + bytes key = 3; + /** + * If set, the new hinTS key the node wants to use when + * the next construction begins. + */ + bytes next_key = 4; +} + +/** + * The output of the hinTS preprocessing algorithm; that is, a + * linear-size aggregation key and a succinct verification key. + */ +message PreprocessedKeys { + /** + * The aggregation key for the hinTS scheme + */ + bytes aggregation_key = 1; + /** + * The succinct verification key for the hinTS scheme. + */ + bytes verification_key = 2; +} + +/** + * The id for a node's vote for the output of the + * preprocessing output of a hinTS construction. + */ +message PreprocessingVoteId { + /** + * The construction this vote is connected to. + */ + uint64 construction_id = 1; + /** + * The id of the node submitting the vote. + */ + uint64 node_id = 2; +} + +/** + * A node's vote for the consensus output of a hinTS preprocessing + * algorithm. + */ +message PreprocessingVote { + oneof vote { + /** + * The preprocessed keys this node is voting for. + */ + PreprocessedKeys preprocessed_keys = 1; + /** + * The id of any node that already voted for the exact keys + * that this node wanted to vote for. + */ + uint64 congruent_node_id = 2; + } +} + +/** + * A node's hinTS party id. + */ +message NodePartyId { + /** + * The node id. + */ + uint64 node_id = 1; + /** + * The party id. + */ + uint32 party_id = 2; +} + +/** + * The information constituting the hinTS scheme Hiero TSS. + */ +message HintsScheme { + /** + * The aggregation and verification keys for the scheme. + */ + PreprocessedKeys preprocessed_keys = 1; + + /** + * The final party ids assigned to each node in the target roster. + */ + repeated NodePartyId node_party_ids = 2; +} + +/** + * A summary of progress in constructing a hinTS scheme. + */ +message HintsConstruction { + /** + * The id of the construction. + */ + uint64 construction_id = 1; + /** + * The hash of the roster whose weights are used to determine when + * the >=1/3 weight signing threshold is reached. + */ + bytes source_roster_hash = 2; + /** + * The hash of the roster whose weights are used to determine when + * the >2/3 weight availability threshold is reached. + */ + bytes target_roster_hash = 3; + + oneof preprocessing_state { + /** + * If the network is still gathering hinTS keys for this construction, + * the time at which honest nodes should stop waiting for tardy + * publications and begin preprocessing as soon as there are valid + * hinTS keys for nodes with >2/3 weight in the target roster. + */ + proto.Timestamp grace_period_end_time = 4; + /** + * If the network has gathered enough hinTS keys for this construction + * to begin preprocessing, the cutoff time by which keys must have been + * adopted to be included as input to the preprocessing algorithm. + */ + proto.Timestamp preprocessing_start_time = 5; + + /** + * If set, the completed hinTS scheme. + */ + HintsScheme hints_scheme = 6; + } +} \ No newline at end of file diff --git a/sdk/src/main/proto/history_proof_key_publication.proto b/sdk/src/main/proto/history_proof_key_publication.proto new file mode 100644 index 000000000..7266f002b --- /dev/null +++ b/sdk/src/main/proto/history_proof_key_publication.proto @@ -0,0 +1,46 @@ +/** + * # Proof Key Publication Transaction + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ +syntax = "proto3"; + +package com.hedera.hapi.services.auxiliary.history; + +/* + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +option java_package = "com.hedera.hapi.services.auxiliary.history.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package + +option java_multiple_files = true; + +/** + * A transaction body to publish a node's history proof key. + */ +message HistoryProofKeyPublicationTransactionBody { + /** + * The proof key the submitting node intends to use when + * contributing signatures for use in proving history + * belongs to the chain of trust for the ledger id. + */ + bytes proof_key = 1; +} diff --git a/sdk/src/main/proto/history_proof_signature.proto b/sdk/src/main/proto/history_proof_signature.proto new file mode 100644 index 000000000..8979b7bf2 --- /dev/null +++ b/sdk/src/main/proto/history_proof_signature.proto @@ -0,0 +1,54 @@ +/** + * # Metadata Proof Assembly Signature Transaction + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ +syntax = "proto3"; + +package com.hedera.hapi.services.auxiliary.history; + +/* + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import "history_types.proto"; + +option java_package = "com.hedera.hapi.services.auxiliary.history.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package + +option java_multiple_files = true; + +/** + * A transaction body to publish a node's signature on a computed + * history of address book hash and associated metadata. This + * signature can contribute to a proof that the history belongs to + * to the chain of trust for the ledger id. + */ +message HistoryProofSignatureTransactionBody { + /** + * The id of the proof construction this signature is contributing to. + */ + uint64 construction_id = 1; + + /** + * This node's signature on its computed history. + */ + com.hedera.hapi.node.state.history.HistorySignature signature = 2; +} diff --git a/sdk/src/main/proto/history_proof_vote.proto b/sdk/src/main/proto/history_proof_vote.proto new file mode 100644 index 000000000..904578122 --- /dev/null +++ b/sdk/src/main/proto/history_proof_vote.proto @@ -0,0 +1,52 @@ +/** + * # Metadata Proof Vote Transaction + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ +syntax = "proto3"; + +package com.hedera.hapi.services.auxiliary.history; + +/* + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import "history_types.proto"; + +option java_package = "com.hedera.hapi.services.auxiliary.history.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package + +option java_multiple_files = true; + +/** + * A transaction body to publish a node's vote for a + * proof of history associated to a construction id. + */ +message HistoryProofVoteTransactionBody { + /** + * The id of the proof construction this vote is for. + */ + uint64 construction_id = 1; + + /** + * The submitting node's vote on the history proof. + */ + com.hedera.hapi.node.state.history.HistoryProofVote vote = 2; +} diff --git a/sdk/src/main/proto/history_types.proto b/sdk/src/main/proto/history_types.proto new file mode 100644 index 000000000..232e3ab9c --- /dev/null +++ b/sdk/src/main/proto/history_types.proto @@ -0,0 +1,222 @@ +syntax = "proto3"; + +package com.hedera.hapi.node.state.history; + +/* + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import "timestamp.proto"; + +option java_package = "com.hedera.hashgraph.sdk.proto"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * A set of proof keys for a node; that is, the key the node is + * currently using and the key it wants to use in assembling the + * next address book in the ledger id's chain of trust. + */ +message ProofKeySet { + /** + * The consensus time when the network adopted the active + * proof key in this set. An adoption time that is sufficiently + * tardy relative to the latest assembly start time may result + * in the node's key being omitted from the address book. + */ + proto.Timestamp adoption_time = 2; + /** + * The proof key the node is using. + */ + bytes key = 3; + /** + * If set, the proof key the node wants to start using in the + * address book. + */ + bytes next_key = 4; +} + +/** + * A record of the proof key a node had in a particular address + * book. Necessary to keep at each point history so that nodes + * can verify the correct key was used to sign in transitions + * starting from the current address book; no matter how keys + * have been rotated from the time the address book was created. + */ +message ProofKey { + /** + * The node id. + */ + uint64 node_id = 1; + /** + * The key. + */ + bytes key = 2; +} + +/** + * A piece of new history in the form of an address book hash and + * associated metadata. + */ +message History { + /** + * The address book hash of the new history. + */ + bytes address_book_hash = 1; + /** + * The metadata associated to the address book. + */ + bytes metadata = 2; +} + +/** + * A proof that some address book history belongs to the ledger id's + * chain of trust. + */ +message HistoryProof { + /** + * The hash of the source address book. + */ + bytes source_address_book_hash = 1; + /** + * The proof keys for the target address book, needed to keep + * constructing proofs after adopting the target address book's + * roster at a handoff. + */ + repeated ProofKey target_proof_keys = 2; + /** + * The target history of the proof. + */ + History target_history = 3; + /** + * The proof of chain of trust from the ledger id. + */ + bytes proof = 4; +} + +/** + * Summary of the status of constructing a metadata proof, necessary to + * ensure deterministic construction ending in a roster with sufficient + * weight to enact its own constructions. + */ +message HistoryProofConstruction { + /** + * The construction id. + */ + uint64 construction_id = 1; + /** + * The hash of the roster whose weights are used to determine when + * certain thresholds are during construction. + */ + bytes source_roster_hash = 2; + /** + * If set, the proof that the address book of the source roster belongs + * to the the ledger id's chain of trust; if not set, the source roster's + * address book must *be* the ledger id. + */ + HistoryProof source_proof = 3; + /** + * The hash of the roster whose weights are used to assess progress + * toward obtaining proof keys for parties that hold at least a + * strong minority of the stake in that roster. + */ + bytes target_roster_hash = 4; + + oneof proof_state { + /** + * If the network is still gathering proof keys for this + * construction, the next time at which nodes should stop waiting + * for tardy proof keys and assembly the history to be proven as + * soon as it has the associated metadata and proof keys for nodes + * with >2/3 weight in the target roster. + */ + proto.Timestamp grace_period_end_time = 5; + /** + * If the network has gathered enough proof keys to assemble the + * history for this construction, the cutoff time at which those + * keys must have been adopted to be included in the final history. + */ + proto.Timestamp assembly_start_time = 6; + /** + * When this construction is complete, the recursive proof that + * the target roster's address book and associated metadata belong + * to the ledger id's chain of trust. + */ + HistoryProof target_proof = 7; + } +} + +/** + * A construction-scoped node id. + */ +message ConstructionNodeId { + /** + * The unique id of a history proof construction. + */ + uint64 construction_id = 1; + /** + * The unique id of a node. + */ + uint64 node_id = 2; +} + +/** + * A node's vote for a particular history proof; either by explicitly + * giving the proof, or by identifying a node that already voted for it. + */ +message HistoryProofVote { + oneof vote { + /** + * The history proof the submitting node is voting for. + */ + HistoryProof proof = 1; + /** + * The id of another node that already voted for the exact proof + * the submitting node is voting for. + */ + uint64 congruent_node_id = 2; + } +} + +/** + * A node's signature blessing some new history. + */ +message HistorySignature { + /** + * The new history the node is signing. + */ + History history = 1; + /** + * The node's signature on the canonical serialization of + * the new history. + */ + bytes signature = 2; +} + +/** + * A signature on some new history recorded at a certain time. + */ +message RecordedHistorySignature { + /** + * The time at which the signature was recorded. + */ + proto.Timestamp signing_time = 1; + + /** + * The signature on some new history. + */ + HistorySignature history_signature = 2; +} + diff --git a/sdk/src/main/proto/ledger_id.proto b/sdk/src/main/proto/ledger_id.proto index a9fd1e703..98e5d42f4 100644 --- a/sdk/src/main/proto/ledger_id.proto +++ b/sdk/src/main/proto/ledger_id.proto @@ -15,7 +15,7 @@ */ syntax = "proto3"; -package com.hedera.hashgraph.hapi.node.state.roster; +package com.hedera.hapi.node.state.roster; /* * Copyright (C) 2024 Hedera Hashgraph, LLC diff --git a/sdk/src/main/proto/network_get_execution_time.proto b/sdk/src/main/proto/network_get_execution_time.proto index fbf9dceb5..6da037a2e 100644 --- a/sdk/src/main/proto/network_get_execution_time.proto +++ b/sdk/src/main/proto/network_get_execution_time.proto @@ -1,13 +1,28 @@ +/** + * # Get Execution Time + * Given a list of transaction identifiers, return the time required to + * process each transaction, excluding pre-consensus processing, consensus, + * and post-processing (e.g. record stream generation). + * + * > Important + * >> This query is obsolete and not supported.
+ * >> Any query of this type that is submitted SHALL fail with a `PRE_CHECK` + * >> result of `NOT_SUPPORTED`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +34,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,38 +45,57 @@ import "query_header.proto"; import "response_header.proto"; /** - * Gets the time in nanoseconds spent in handleTransaction for one or more - * TransactionIDs (assuming they have reached consensus "recently", since only a limited - * number of execution times are kept in-memory, depending on the value of the node-local - * property stats.executionTimesToTrack). + * Retrieve the time, in nanoseconds, spent in direct processing for one + * or more recent transactions. + * + * For each transaction identifier provided, if that transaction is + * sufficiently recent (that is, it is within the range of the configuration + * value `stats.executionTimesToTrack`), the node SHALL return the time, in + * nanoseconds, spent to directly process that transaction.
+ * This time will generally correspond to the time spent in a `handle` call + * within the workflow. + * + * Note that because each node processes every transaction for the Hedera + * network, this query MAY be sent to any node, and results MAY be different + * between different nodes. + * */ message NetworkGetExecutionTimeQuery { - /** - * 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; + option deprecated = true; + /** + * Standard information sent with every query operation.
+ * This includes the signed payment and what kind of response is requested + * (cost, state proof, both, or neither). + */ + QueryHeader header = 1; - /** - * The id(s) of the transactions to get the execution time(s) of - */ - repeated TransactionID transaction_ids = 2; + /** + * A list of transaction identifiers to query. + *

+ * All of the queried transaction identifiers MUST have execution time + * available. If any identifier does not have available execution time, + * the query SHALL fail with an `INVALID_TRANSACTION_ID` response. + */ + repeated TransactionID transaction_ids = 2; } /** - * Response when the client sends the node NetworkGetExecutionTimeQuery; returns - * INVALID_TRANSACTION_ID if any of the given TransactionIDs do not have available - * execution times in the answering node. + * A response to a `networkGetExecutionTime` query. */ message NetworkGetExecutionTimeResponse { + option deprecated = true; /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * The execution time(s) of the requested TransactionIDs, if available + * A list of execution times, in nanoseconds. + *

+ * This list SHALL be in the same order as the transaction + * identifiers were presented in the query. */ repeated uint64 execution_times = 2; } diff --git a/sdk/src/main/proto/network_get_version_info.proto b/sdk/src/main/proto/network_get_version_info.proto index 64978788d..fc3d82c36 100644 --- a/sdk/src/main/proto/network_get_version_info.proto +++ b/sdk/src/main/proto/network_get_version_info.proto @@ -1,13 +1,21 @@ +/** + * # Get Version + * Standard query for services and API message versions. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,33 +38,45 @@ import "query_header.proto"; import "response_header.proto"; /** - * Get the deployed versions of Hedera Services and the HAPI proto in semantic version format + * Query the deployed versions of Hedera Services and the API definitions in + * semantic version format */ message NetworkGetVersionInfoQuery { /** - * 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 information sent with every query operation.
+ * This includes 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 + * A response to a `NetworkGetVersionInfoQuery`. + * + * This SHALL return `SemanticVersion` information for both Hedera API (HAPI) + * and Hedera Services. */ message NetworkGetVersionInfoResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * The Hedera API (HAPI) protobuf version recognized by the responding node. + * An API version. + *

+ * This SHALL be the current Hedera API (HAPI) protobuf message version + * accepted by the network. */ SemanticVersion hapiProtoVersion = 2; /** - * The version of the Hedera Services software deployed on the responding node. + * A Services version. + *

+ * This SHALL be the current version of the Hedera Services software + * operating the network. */ SemanticVersion hederaServicesVersion = 3; } diff --git a/sdk/src/main/proto/network_service.proto b/sdk/src/main/proto/network_service.proto index c17810fa4..cf9aa23c7 100644 --- a/sdk/src/main/proto/network_service.proto +++ b/sdk/src/main/proto/network_service.proto @@ -1,13 +1,21 @@ +/** + * # Network Service + * This service offers some basic "network information" queries. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,33 +38,51 @@ import "transaction_response.proto"; import "transaction.proto"; /** - * The requests and responses for different network services. + * Basic "network information" queries. + * + * This service supports queries for the active services and API versions, + * and a query for account details. */ service NetworkService { /** - * Retrieves the active versions of Hedera Services and HAPI proto + * Retrieve the active versions of Hedera Services and API messages. */ rpc getVersionInfo (Query) returns (Response); /** - * Retrieves the time in nanoseconds spent in handleTransaction for one or more - * TransactionIDs (assuming they have reached consensus "recently", since only a limited - * number of execution times are kept in-memory, depending on the value of the node-local - * property stats.executionTimesToTrack). + * Request detail information about an account. + *

+ * The returned information SHALL include balance and allowances.
+ * The returned information SHALL NOT include a list of account records. */ - rpc getExecutionTime (Query) returns (Response); + rpc getAccountDetails (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.) + * Retrieve the time, in nanoseconds, spent in direct processing for one or + * more recent transactions. + *

+ * For each transaction identifier provided, if that transaction is + * sufficiently recent (that is, it is within the range of the + * configuration value `stats.executionTimesToTrack`), the node SHALL + * return the time, in nanoseconds, spent to directly process that + * transaction (that is, excluding time to reach consensus).
+ * Note that because each node processes every transaction for the Hedera + * network, this query MAY be sent to any node. + *

+ *

Important
+ * This query is obsolete, not supported, and SHALL fail with a pre-check + * result of `NOT_SUPPORTED`.
*/ - rpc uncheckedSubmit (Transaction) returns (TransactionResponse); + rpc getExecutionTime (Query) returns (Response) {option deprecated = true;}; /** - * Get all the information about an account, including balance and allowances. This does not get the list of - * account records. + * Submit a transaction that wraps another transaction which will + * skip most validation. + *

+ *

Important
+ * This query is obsolete, not supported, and SHALL fail with a pre-check + * result of `NOT_SUPPORTED`. + *
*/ - rpc getAccountDetails (Query) returns (Response); + rpc uncheckedSubmit (Transaction) returns (TransactionResponse) {option deprecated = true;}; } diff --git a/sdk/src/main/proto/network_staking_rewards.proto b/sdk/src/main/proto/network_staking_rewards.proto index 66d99530e..0b7f50f6b 100644 --- a/sdk/src/main/proto/network_staking_rewards.proto +++ b/sdk/src/main/proto/network_staking_rewards.proto @@ -1,13 +1,21 @@ +/** + * # Network Staking Rewards + * The information needed to calculate the staking rewards for all nodes in + * the network. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,36 +34,52 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** - * Representation of a Hedera Token Service staking reward entity in the network Merkle tree. - * This consists of all the information needed to calculate the staking rewards for all nodes in the network. It is - * calculated at the beginning of each staking period for all nodes and is needed to have same values - * for reconnect. - * - * As with all network entities, staking info is per node and has a unique entity number represented as shard.realm.X. + * An Hedera Token Service staking reward entity. + * This stores values related to the aggregate staking rewards for all nodes in + * the network. It is calculated at the beginning of each staking period. */ message NetworkStakingRewards { - /** - * Whether staking rewards are activated on the network. This is set to true when the balance of 0.0.800 - * reaches minimum required balance. - */ - bool staking_rewards_activated = 1; - - /** - * Total of (balance + stakedToMe) for all accounts staked to all nodes in the network with declineReward=false, at the - * beginning of the new staking period. - */ - int64 total_staked_reward_start = 2; - - /** - * Total of (balance + stakedToMe) for all accounts staked to all nodes in the network, at the beginning of the new - * staking period. - */ - int64 total_staked_start = 3; - - /** - * The total staking rewards in tinybars that COULD be collected by all accounts staking to all nodes after the end - * of this staking period; assuming that no account "renounces" its rewards by, for example, setting declineReward=true. - */ - int64 pending_rewards = 4; + /** + * A flag indicating that staking rewards are activated on the network. + *

+ * Among other criteria, this is set to true when the balance of 0.0.800 + * (the account that pays rewards) reaches a minimum required balance. + */ + bool staking_rewards_activated = 1; + + /** + * A global snapshot of the `stake_to_reward` value for all nodes at the + * beginning of the current staking period. + *

+ * The `stake_to_reward` value is the sum of balance and `staked_to_me` for + * all accounts staked to a node that do not decline staking rewards.
+ * This is needed for calculating rewards for current staking period without + * considering changes to `stake_to_reward` within the current staking period.
+ * This value SHALL be reset at the beginning of every staking period. + */ + int64 total_staked_reward_start = 2; + + /** + * A global snapshot of the `stake` value for all nodes at the beginning of + * the current staking period. + *

+ * The `stake` value is the sum of balance and `staked_to_me` for all + * accounts staked to a node, and SHALL NOT consider whether the account + * has accepted or declined rewards.
+ * This value SHALL be reset at the beginning of every staking period. + */ + int64 total_staked_start = 3; + + /** + * The total staking rewards, in tinybars, that may be collected by all + * accounts staking to all nodes after the end of this staking period. + *

+ * This SHALL be calculated assuming that no account "renounces" its + * rewards by setting `decline_reward` to true, or is ineligible for some + * other reason.
+ * If a node is removed, the `pending_rewards` value of that node SHALL be + * subtracted from this value. + */ + int64 pending_rewards = 4; } diff --git a/sdk/src/main/proto/nft.proto b/sdk/src/main/proto/nft.proto index 83db330af..6ccbdc47f 100644 --- a/sdk/src/main/proto/nft.proto +++ b/sdk/src/main/proto/nft.proto @@ -1,13 +1,20 @@ +/** + * # NFT. + * This is a single, whole, unique, non-fungible token within the Hedera network. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +26,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ import "timestamp.proto"; @@ -30,48 +36,67 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** - * Representation of a Hedera Token Service NFT in the network Merkle tree. + * An Hedera Token Service non-fungible token (NFT).
+ * Every NFT is a unique instance of a token with non-fungible type. + * + * The NFT SHALL be identified by token ID and serial number.
+ * The token treasury account SHALL own all minted NFTs of that token type + * initially.
+ * NFTs owned by the token treasury SHALL NOT be linked into that account's + * virtual linked list of NFTs.
+ * NFTs not owned by the token treasury SHALL be linked into the owner + * account's virtual linked list of NFTs. */ message Nft { /** - * The id of this NFT. + * The id of this NFT, consisting of a Token ID and serial number. */ NftID nft_id = 1; /** * The account or contract id that owns this NFT. - * - * If this number is zero in state, the NFT is owned by its token type's current treasury. + *

+ * If this NFT is owned by its token type's current treasury account, + * this value SHALL be zero. */ AccountID owner_id = 2; /** * The account or contract id approved to spend this NFT. - * - * If this number is zero, there is no approved spender. + *

+ * If there is no approved spender, this value SHALL be null. */ AccountID spender_id = 3; /** - * The consensus time of the TokenMint that created this NFT. + * The consensus time of the TokenMint that created this NFT as + * offset from the epoch. + *

+ * For this purpose, `epoch` SHALL be the UNIX epoch with 0 at `1970-01-01T00:00:00.000Z`. */ Timestamp mint_time = 4; /** - * The metadata of this NFT, up to 100 bytes; usually the UTF-8 encoding of a URI. + * The metadata bytes for this NFT. This is often a URI value. + *

+ * This value, if set, SHALL NOT exceed 100 bytes. */ bytes metadata = 5; /** - * If the owner of this NFT is not its token treasury, the id of the previous NFT - * in the owner's "doubly-linked list" of owned NFTs (if any). + * The NFT ID of the previous entry in the current owner's "virtual + * double-linked list" of owned NFTs. + *

+ * If the owner of this NFT is the token treasury, this SHALL be unset. */ NftID owner_previous_nft_id = 6; /** - * If the owner of this NFT is not its token treasury, the id of the next NFT in - * the owner's "doubly-linked list" of owned NFTs (if any). + * The NFT ID of the next entry in the current owner's "virtual + * double-linked list" of owned NFTs. + *

+ * If the owner of this NFT is the token treasury, this SHALL be unset. */ NftID owner_next_nft_id = 7; } diff --git a/sdk/src/main/proto/node.proto b/sdk/src/main/proto/node.proto index 2fbf307cb..ed4de6919 100644 --- a/sdk/src/main/proto/node.proto +++ b/sdk/src/main/proto/node.proto @@ -1,6 +1,6 @@ syntax = "proto3"; -package com.hedera.hashgraph.hapi.node.state.addressbook; +package com.hedera.hapi.node.state.addressbook; /* * Copyright (C) 2024 Hedera Hashgraph, LLC @@ -39,9 +39,7 @@ message Node { /** * A consensus node identifier. *

- * Node identifiers SHALL be unique _within_ a shard and realm, - * but a node SHALL NOT, ever, serve multiple shards or realms, - * therefore the node identifier MAY be repeated _between_ shards and realms. + * Node identifiers SHALL be globally unique for a given ledger. */ uint64 node_id = 1; @@ -49,15 +47,19 @@ message Node { * An account identifier. *

* This account SHALL be owned by the entity responsible for the node.
- * This account SHALL be charged transaction fees for any transactions that - * are submitted to the network by this node and fail due diligence checks. + * This account SHALL be charged transaction fees for any transactions + * that are submitted to the network by this node and + * fail due diligence checks.
+ * This account SHALL be paid the node portion of transaction fees + * for transactions submitted by this node. */ proto.AccountID account_id = 2; /** * A short description of the node. *

- * This value, if set, SHALL NOT exceed 100 bytes when encoded as UTF-8. + * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string description = 3; @@ -80,7 +82,7 @@ message Node { repeated proto.ServiceEndpoint gossip_endpoint = 4; /** - * A list of service endpoints for gRPC calls. + * A list of service endpoints for client calls. *

* These endpoints SHALL represent the published endpoints to which clients * may submit transactions.
@@ -123,8 +125,11 @@ message Node { * of HBAR staked to that node.
* Consensus SHALL be calculated based on agreement of greater than `2/3` * of the total `weight` value of all nodes on the network. + *

+ * This field is deprecated and SHALL NOT be used when RosterLifecycle + * is enabled. */ - uint64 weight = 8; + uint64 weight = 8 [deprecated = true]; /** * A flag indicating this node is deleted. @@ -139,7 +144,7 @@ message Node { bool deleted = 9; /** - * An administrative key controlled by the node operator. + * An administrative key controlled by the node operator. *

* This key MUST sign each transaction to update this node.
* This field MUST contain a valid `Key` value.
diff --git a/sdk/src/main/proto/node_create.proto b/sdk/src/main/proto/node_create.proto index 39b153018..ad3c837f7 100644 --- a/sdk/src/main/proto/node_create.proto +++ b/sdk/src/main/proto/node_create.proto @@ -1,6 +1,6 @@ syntax = "proto3"; -package com.hedera.hashgraph.hapi.node.addressbook; +package com.hedera.hapi.node.addressbook; /* * Copyright (C) 2024 Hedera Hashgraph, LLC @@ -33,9 +33,9 @@ import "basic_types.proto"; * address book. The transaction, once complete, enables a new consensus node * to join the network, and requires governing council authorization. * - * - A `NodeCreateTransactionBody` MUST be signed by the governing council. * - A `NodeCreateTransactionBody` MUST be signed by the `Key` assigned to the - * `admin_key` field. + * `admin_key` field and one of those keys: treasure account (2) key, + * systemAdmin(50) key, or addressBookAdmin(55) key. * - The newly created node information SHALL be added to the network address * book information in the network state. * - The new entry SHALL be created in "state" but SHALL NOT participate in @@ -45,9 +45,11 @@ import "basic_types.proto"; * configuration during the next `freeze` transaction with the field * `freeze_type` set to `PREPARE_UPGRADE`. * - * ### Record Stream Effects - * Upon completion the newly assigned `node_id` SHALL be in the transaction - * receipt. + * ### Block Stream Effects + * Upon completion the newly assigned `node_id` SHALL be recorded in + * the transaction receipt.
+ * This value SHALL be the next available node identifier.
+ * Node identifiers SHALL NOT be reused. */ message NodeCreateTransactionBody { /** @@ -64,7 +66,8 @@ message NodeCreateTransactionBody { /** * A short description of the node. *

- * This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.
+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8.
* This field is OPTIONAL. */ string description = 2; diff --git a/sdk/src/main/proto/node_delete.proto b/sdk/src/main/proto/node_delete.proto index 146747274..48395312c 100644 --- a/sdk/src/main/proto/node_delete.proto +++ b/sdk/src/main/proto/node_delete.proto @@ -1,6 +1,6 @@ syntax = "proto3"; -package com.hedera.hashgraph.hapi.node.addressbook; +package com.hedera.hapi.node.addressbook; /* * Copyright (C) 2024 Hedera Hashgraph, LLC diff --git a/sdk/src/main/proto/node_stake_update.proto b/sdk/src/main/proto/node_stake_update.proto index ea2a32c13..c183c03fd 100644 --- a/sdk/src/main/proto/node_stake_update.proto +++ b/sdk/src/main/proto/node_stake_update.proto @@ -1,13 +1,33 @@ +/** + * # Node Stake Updates + * A system-initiated (i.e. internal) transaction to update stake information + * for nodes at the end of a staking period. + * + * Note that staking rewards are not paid immediately. The rewards are + * calculated, and the amount to be paid is reserved in the reward account, + * at the end of each staking period. The actual recipient accounts are then + * paid rewards when that account participates in any transaction that + * changes staking information or the account balance. This reduces the + * resources for calculating the staking rewards, quite dramatically, + * and provides an incentive for account owners to engage with the network, + * in at least a minor fashion, occasionally (typically annually).
+ * The unexpected change in balances, however, can be surprising to the + * account holder. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +39,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -30,136 +49,228 @@ import "basic_types.proto"; import "timestamp.proto"; /** - * Updates the staking info at the end of staking period to indicate new staking period has started. + * A system initiated transaction to update staking information. + * + * This transaction SHALL be issued at the end of each staking period to update + * node stakes and reward limits.
+ * This transaction SHALL be a child of the first transaction to reach + * consensus following the end of the previous staking period.
+ * This transaction MUST NOT be sent by a client and SHALL be rejected if + * received by any node.
+ * This transaction SHALL be present in the record stream or block stream. + * + * ### Block Stream Effects + * None */ message NodeStakeUpdateTransactionBody { - /** - * Time and date of the end of the staking period that is ending - */ - Timestamp end_of_staking_period = 1; - - /** - * Staking info of each node at the beginning of the new staking period - */ - repeated NodeStake node_stake = 2; - - /** - * The maximum reward rate, in tinybars per whole hbar, that any account could receive in this - * staking period. - */ - int64 max_staking_reward_rate_per_hbar = 3; - - /** - * The fraction of the network and service fees paid to the node reward account 0.0.801. - */ - Fraction node_reward_fee_fraction = 4; - - /** - * The maximum number of trailing periods for which a user can collect rewards. For example, if this - * is 365 with a UTC calendar day period, then users must collect rewards at least once per calendar - * year to avoid missing any value. - */ - int64 staking_periods_stored = 5; - - /** - * The number of minutes in a staking period. Note for the special case of 1440 minutes, periods are - * treated as UTC calendar days, rather than repeating 1440 minute periods left-aligned at the epoch. - */ - int64 staking_period = 6; - - /** - * The fraction of the network and service fees paid to the staking reward account 0.0.800. - */ - Fraction staking_reward_fee_fraction = 7; - - /** - * The minimum balance of staking reward account 0.0.800 required to active rewards. - */ - int64 staking_start_threshold = 8; - - /** - * (DEPRECATED) The maximum total number of tinybars to be distributed as staking rewards in the - * ending period. Please consult the max_total_reward field instead. - */ - int64 staking_reward_rate = 9 [deprecated = true]; - - /** - * The amount of the staking reward funds (account 0.0.800) reserved to pay pending rewards that - * have been earned but not collected. - */ - int64 reserved_staking_rewards = 10; - - /** - * The unreserved balance of account 0.0.800 at the close of the just-ending period; this value is - * used to compute the HIP-782 balance ratio. - */ - int64 unreserved_staking_reward_balance = 11; - - /** - * The unreserved tinybar balance of account 0.0.800 required to achieve the maximum per-hbar reward - * rate in any period; please see HIP-782 for details. - */ - int64 reward_balance_threshold = 12; - - /** - * The maximum amount of tinybar that can be staked for reward while still achieving the maximum - * per-hbar reward rate in any period; please see HIP-782 for details. - */ - int64 max_stake_rewarded = 13; - - /** - * The maximum total tinybars that could be paid as staking rewards in the ending period, after - * applying the settings for the 0.0.800 balance threshold and the maximum stake rewarded. This - * field replaces the deprecated field staking_reward_rate. It is only for convenience, since a - * mirror node could also calculate its value by iterating the node_stake list and summing - * stake_rewarded fields; then multiplying this sum by the max_staking_reward_rate_per_hbar. - */ - int64 max_total_reward = 14; + /** + * A timestamp indicating the end of the staking period. + *

+ * This value SHALL be one nanosecond prior to midnight prior to the + * consensus time of the parent transaction. + */ + Timestamp end_of_staking_period = 1; + + /** + * A list of `NodeStake` entries for each node at the beginning of the new + * staking period. + *

+ * This list SHALL have one entry for each node participating in network + * consensus. + */ + repeated NodeStake node_stake = 2; + + /** + * A maximum reward rate for this staking period. + *

+ * This SHALL be a ratio of tinybar to HBAR.
+ * An account SHALL NOT receive a reward greater than the product of this + * ratio and the total number of HBAR staked by that account. + */ + int64 max_staking_reward_rate_per_hbar = 3; + + /** + * A fraction of network and service fees paid to + * the "node" reward account.
+ * The node staking rewards are paid from the designated reward account + * `0.0.801`, which receives a fraction of network and service fees for + * each transaction. This field is the value of that fraction for the + * last staking period. + */ + Fraction node_reward_fee_fraction = 4; + + /** + * A limit to the number of staking periods held for inactive accounts.
+ * This is the maximum number of trailing staking periods for which an + * account can collect staking rewards.
+ * #### Example + * If this value is 365 with a calendar day period, then each account must + * collect rewards at least once per calendar year to receive the full + * amount of staking rewards earned. + *

+ * Staking rewards SHALL be stored in network state for no more than + * `staking_periods_stored` staking periods.
+ * Each account MUST participate in at least one transaction that affects + * its balance, staking, or staking metadata within this time limit + * to receive all available staking rewards. + */ + int64 staking_periods_stored = 5; + + /** + * A number of minutes representing a staking period.
+ *

Note
+ * For the special case of `1440` minutes, periods are treated as + * calendar days aligned to midnight UTC, rather than repeating `1440` + * minute periods left-aligned at the epoch.
+ */ + int64 staking_period = 6; + + /** + * A fraction of network and service fees paid to + * the "general" reward account.
+ * The general staking rewards are paid from the designated reward account + * `0.0.800`, which receives a fraction of network and service fees for + * each transaction. This field is the value of that fraction for the + * last staking period. + */ + Fraction staking_reward_fee_fraction = 7; + + /** + * A minimum balance required to pay general staking rewards. + *

+ * If the balance of the staking reward account `0.0.800` is below this + * threshold, staking rewards SHALL NOT be paid in full. + */ + int64 staking_start_threshold = 8; + + /** + * HIP-786 replaced this field with `max_total_reward`.
+ * This was a maximum total number of tinybars to be distributed as staking + * rewards in the staking period that just ended. + */ + int64 staking_reward_rate = 9 [deprecated = true]; + + /** + * An amount reserved in the staking reward account.
+ * This is an amount "reserved" in the balance of account `0.0.800` that + * is already owed for pending rewards that were previously earned but + * have not yet been collected.
+ * This value is further detailed in HIP-786. + */ + int64 reserved_staking_rewards = 10; + + /** + * An available, unreserved, amount in the staking reward account.
+ * This is the balance of the staking reward account `0.0.800` at the close + * of the staking period that just ended, after reduction for all "reserved" + * funds necessary to pay previously earned rewards.
+ * This value is further detailed in HIP-786. + *

+ * This value SHALL be used to calculate the reward ratio according to + * the formula detailed in HIP-782. + */ + int64 unreserved_staking_reward_balance = 11; + + /** + * A minimum balance required for maximum staking rewards.
+ * This value is further detailed in HIP-786. + * The formula to calculate staking rewards is detailed in HIP-782. + *

+ * The value of `unreserved_staking_reward_balance` MUST match or exceed the + * value of this field to support the maximum staking reward ratio.
+ */ + int64 reward_balance_threshold = 12; + + /** + * A maximum network-wide stake that can earn full rewards.
+ * If the network-wide stake, in tinybar, exceeds this value, then staking + * rewards must be reduced to maintain "smooth" reward adjustments as + * defined in HIP-782.
+ * This value is further detailed in HIP-786. + *

+ * If the total network-wide stake exceeds this value, the effective + * staking reward ratio MUST be reduced to maintain solvency of the + * staking reward account. + */ + int64 max_stake_rewarded = 13; + + /** + * A limit amount that could be paid as staking rewards.
+ * In the limit case, the network could pay at most this amount, in tinybar + * as staking rewards for the staking period that just ended, if all other + * conditions were met to perfection.
+ *

+ * This value SHALL reflect the result of a maximum reward calculation that + * takes into account the balance thresholds and maximum stake thresholds + * as defined in HIP-782 and HIP-786.
+ * This value is a convenience. The actual defined calculation SHALL be + * authoritative in the unlikely event this value differs. + */ + int64 max_total_reward = 14; } /** - * Staking info for each node at the end of a staking period. + * Staking information for one node at the end of a staking period. + * + * This SHALL be one entry in a list reported at the end of each + * full staking period. */ message NodeStake { - /** - * The maximum stake (rewarded or not rewarded) this node can have as consensus weight. If its stake to - * reward is above this maximum at the start of a period, then accounts staking to the node in that - * period will be rewarded at a lower rate scaled by (maxStake / stakeRewardStart). - */ - int64 max_stake = 1; - - /** - * The minimum stake (rewarded or not rewarded) this node must reach before having non-zero consensus weight. - * If its total stake is below this minimum at the start of a period, then accounts staking to the node in - * that period will receive no rewards. - */ - int64 min_stake = 2; - - /** - * The id of this node. - */ - int64 node_id = 3; - - /** - * The reward rate _per whole hbar_ that was staked to this node with declineReward=false from the start of - * the staking period that is ending. - */ - int64 reward_rate = 4; - - /** - * Consensus weight of this node for the new staking period. - */ - int64 stake = 5; - - /** - * Total of (balance + stakedToMe) for all accounts staked to this node with declineReward=true, at the - * beginning of the new staking period. - */ - int64 stake_not_rewarded = 6; - - /** - * Total of (balance + stakedToMe) for all accounts staked to this node with declineReward=false, at the - * beginning of the new staking period. - */ - int64 stake_rewarded = 7; + /** + * A limit to the amount of stake considered for consensus weight. + *

+ * The amount of stake (whether accepting rewards or not) assigned to a + * node that exceeds this limit SHALL NOT be considered for + * consensus weight calculation.
+ * If stake to _reward_ for a node exceeds this threshold, then all + * accounts staking to that node SHALL receive a lower reward rate in + * proportion to the excess stake. + */ + int64 max_stake = 1; + + /** + * A minimum amount of HBAR staked to a node to receive rewards. + *

+ * If the amount of stake (whether accepting rewards or not) assigned to + * a node at the start of a staking period is less than this threshold, + * then no rewards SHALL be paid to that node or to any accounts + * staking to that node. + */ + int64 min_stake = 2; + + /** + * A node identifier.
+ * This value uniquely identifies this node within the + * network address book. + */ + int64 node_id = 3; + + /** + * The rate of rewards, in tinybar per HBAR, for the staking reward + * period that just ended. + */ + int64 reward_rate = 4; + + /** + * A consensus weight assigned to this node for the next staking period. + */ + int64 stake = 5; + + /** + * The total amount staked to this node, while declining rewards. + *

+ * This SHALL be the total staked amount, in tinybar, that is staked to + * this node with the value of the `decline_reward` set.
+ * This value MUST be calculated at the beginning of the staking period. + */ + int64 stake_not_rewarded = 6; + + /** + * The total amount staked to this node, while accepting rewards. + *

+ * This SHALL be the total staked amount, in tinybar, that is staked to + * this node with the value of the `decline_reward` not set.
+ * This value MUST be calculated at the beginning of the staking period. + */ + int64 stake_rewarded = 7; } diff --git a/sdk/src/main/proto/node_update.proto b/sdk/src/main/proto/node_update.proto index b352e5793..d77d0c41a 100644 --- a/sdk/src/main/proto/node_update.proto +++ b/sdk/src/main/proto/node_update.proto @@ -1,6 +1,6 @@ syntax = "proto3"; -package com.hedera.hashgraph.hapi.node.addressbook; +package com.hedera.hapi.node.addressbook; /* * Copyright (C) 2024 Hedera Hashgraph, LLC @@ -66,7 +66,8 @@ message NodeUpdateTransactionBody { /** * A short description of the node. *

- * This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.
+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8.
* If set, this value SHALL replace the previous value. */ google.protobuf.StringValue description = 3; diff --git a/sdk/src/main/proto/primitives.proto b/sdk/src/main/proto/primitives.proto index 7917055e1..145360059 100644 --- a/sdk/src/main/proto/primitives.proto +++ b/sdk/src/main/proto/primitives.proto @@ -1,8 +1,23 @@ +/** + * # Primitives + * Primitive value wrapper messages. + * + * These SHALL be used only for situations where the entire value to be stored + * in state is a single primitive. These MUST NOT ever be used as components of + * another message; use the protobuf type instead. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; + /* - * Copyright (C) 2023 Hedera Hashgraph, LLC + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -17,13 +32,6 @@ package proto; * limitations under the License. */ -/** - * This proto file contains primitive value messages. - * These are intended only for situations where the entire value to be stored in state is a single - * primitive. These should never be used as components of another message; use the protobuf - * type instead. - */ - option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; @@ -62,4 +70,3 @@ message ProtoString { message ProtoBytes { bytes value = 1; } - diff --git a/sdk/src/main/proto/query.proto b/sdk/src/main/proto/query.proto index 7bf38eb0c..a0a4b7c0c 100644 --- a/sdk/src/main/proto/query.proto +++ b/sdk/src/main/proto/query.proto @@ -1,3 +1,18 @@ +/** + * # Query + * This is the parent message for all queries, and this message is + * serialized and signed, with the signature included in the QueryHeader. + * + * All of the entries in the `query` `oneof` are fully specified elsewhere; + * we only include a short summary here. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; @@ -58,136 +73,173 @@ import "token_get_nft_infos.proto"; import "get_account_details.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 query transaction.
+ * This message is serialized to bytes and those bytes are signed by the + * submitter, with the signature included in the QueryHeader for the query + * request. */ message Query { oneof query { /** - * Get all entities associated with a given key + * 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 + * Get an Hedera identifier associated with an identifier in EVM + * "Solidity" form.
+ * Most often used in smart contracts to find an Hedera account, + * file, or contract identifier to pass to a system contract or + * precompile. */ GetBySolidityIDQuery getBySolidityID = 2; /** - * Call a function of a smart contract instance + * Call a function of a smart contract.
+ * This call is executed exclusively on the node to which it is + * submitted, and is much less expensive than a `contractCall` + * transaction. */ ContractCallLocalQuery contractCallLocal = 3; /** - * Get information about a smart contract instance + * Get information about a smart contract. */ ContractGetInfoQuery contractGetInfo = 4; /** - * Get runtime code used by a smart contract instance + * Get runtime bytecode used by a smart contract. */ ContractGetBytecodeQuery contractGetBytecode = 5; /** - * Get Records of the contract instance + * This query is unsupported and SHALL fail.
+ * Requests for this information MUST be directed to a mirror node. + *

+ * Get Records of a smart contract. */ - ContractGetRecordsQuery ContractGetRecords = 6; - + ContractGetRecordsQuery ContractGetRecords = 6 [deprecated = true]; /** - * Get the current balance in a cryptocurrency account + * Get the current HBAR balance of an Hedera account or smart contract. */ CryptoGetAccountBalanceQuery cryptogetAccountBalance = 7; /** - * Get all the records that currently exist for transactions involving an account + * Get records of all "recent" transactions for which a specified + * account is the effective payer. */ CryptoGetAccountRecordsQuery cryptoGetAccountRecords = 8; /** - * Get all information about an account + * Get information about an account, including the balance.
+ * This does not get the list of account records. */ CryptoGetInfoQuery cryptoGetInfo = 9; /** - * Get a single livehash from a single account, if present + * This query is unsupported and SHALL fail.
+ * Requests for this information MUST be directed to a mirror node. + *

+ * Get a single livehash from a single account, if present. */ - CryptoGetLiveHashQuery cryptoGetLiveHash = 10; + CryptoGetLiveHashQuery cryptoGetLiveHash = 10 [deprecated = true]; /** - * Get all the accounts that proxy stake to a given account, and how much they proxy stake - * (not yet implemented in the current API) + * This query is unsupported and SHALL fail.
+ * Requests for this information MUST be directed to a mirror node. + *

+ * Get all the accounts that are proxy staking to this account. */ - CryptoGetStakersQuery cryptoGetProxyStakers = 11; + CryptoGetStakersQuery cryptoGetProxyStakers = 11 [deprecated = true]; /** - * Get the contents of a file (the bytes stored in it) + * Get the content of a file. */ FileGetContentsQuery fileGetContents = 12; /** - * Get information about a file, such as its expiration date + * Get metadata for a file. */ FileGetInfoQuery fileGetInfo = 13; /** - * Get a receipt for a transaction (lasts 180 seconds) + * Get a receipt for a transaction.
+ * This only returns a receipt if the transaction is "recent", which + * is typically within the previous 180 seconds (3 minutes). */ TransactionGetReceiptQuery transactionGetReceipt = 14; /** - * Get a record for a transaction + * Get a record for a transaction. + * This only returns a record if the transaction is "available", which + * is typically within the previous 1 hour. */ TransactionGetRecordQuery transactionGetRecord = 15; /** - * Get a record for a transaction (lasts 180 seconds) + * Get a record for a transaction. + * This only returns a record if the transaction is "recent", which + * is typically within the previous 180 seconds (3 minutes). */ TransactionGetFastRecordQuery transactionGetFastRecord = 16; /** - * Get the parameters of and state of a consensus topic. + * Get metadata for a consensus topic. */ ConsensusGetTopicInfoQuery consensusGetTopicInfo = 50; /** - * Get the versions of the HAPI protobuf and Hedera Services software deployed on the - * responding node. + * Get the versions of Hedera Services and the HAPI API deployed on + * the responding consensus node. */ NetworkGetVersionInfoQuery networkGetVersionInfo = 51; /** - * Get all information about a token + * Get metadata for a token. */ TokenGetInfoQuery tokenGetInfo = 52; /** - * Get all information about a scheduled entity + * Get metadata for a schedule.
+ * A schedule is a request to execute a transaction at a future + * time. */ ScheduleGetInfoQuery scheduleGetInfo = 53; /** - * Get a list of NFTs associated with the account + * This query is unsupported and SHALL fail.
+ * Requests for this information MUST be directed to a mirror node. + *

+ * Get a list of non-fungible/unique tokens associated with an account. */ - TokenGetAccountNftInfosQuery tokenGetAccountNftInfos = 54; + TokenGetAccountNftInfosQuery tokenGetAccountNftInfos = 54 [deprecated = true]; /** - * Get all information about a NFT + * Get metadata for a specific, serial numbered, non-fungible/unique + * token (NFT). */ TokenGetNftInfoQuery tokenGetNftInfo = 55; /** - * Get a list of NFTs for the token + * This query is unsupported and SHALL fail.
+ * Requests for this information MUST be directed to a mirror node. + *

+ * Get metadata for all non-fungible/unique tokens (NFTs) of a single + * type within a range of indices (0-based count of minted tokens). */ - TokenGetNftInfosQuery tokenGetNftInfos = 56; + TokenGetNftInfosQuery tokenGetNftInfos = 56 [deprecated = true]; /** - * Gets handleTransaction times for one or more "sufficiently recent" TransactionIDs + * This query is unsupported and SHALL fail.
+ * Requests for this information MUST be directed to a mirror node. + *

+ * Get the execution time for a recent transaction. */ - NetworkGetExecutionTimeQuery networkGetExecutionTime = 57; + NetworkGetExecutionTimeQuery networkGetExecutionTime = 57 [deprecated = true]; /** - * Gets all information about an account including allowances granted by the account + * Get detail metadata for an account. */ GetAccountDetailsQuery accountDetails = 58; } diff --git a/sdk/src/main/proto/query_header.proto b/sdk/src/main/proto/query_header.proto index 1bbf256a1..746583f4f 100644 --- a/sdk/src/main/proto/query_header.proto +++ b/sdk/src/main/proto/query_header.proto @@ -1,13 +1,21 @@ +/** + * # Query Header + * Messages that comprise a header sent with each query request. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,48 +36,61 @@ 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 type of query response.
+ * + * This SHALL be answer-only as a default.
+ * This value SHALL support an "estimated cost" type.
+ * This value SHOULD support a "state proof" type, when available. */ enum ResponseType { /** - * Response returns answer + * A response with the query answer. */ ANSWER_ONLY = 0; /** - * (NOT YET SUPPORTED) Response returns both answer and state proof + * A response with both the query answer and a state proof. */ ANSWER_STATE_PROOF = 1; /** - * Response returns the cost of answer + * A response with the estimated cost to answer the query. */ COST_ANSWER = 2; /** - * (NOT YET SUPPORTED) Response returns the total cost of answer and state proof + * A response with the estimated cost to answer and a 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. + * A standard query header.
+ * Each query from the client to the node must contain a QueryHeader, which + * specifies the desired response type, and includes a payment transaction + * that will compensate the network for responding to the query. + * The payment may be blank if the query is free. + * + * The payment transaction MUST be a `cryptoTransfer` from the payer account + * to the account of the node where the query is submitted.
+ * If the payment is sufficient, the network SHALL respond with the response + * type requested.
+ * If the response type is `COST_ANSWER` the payment MUST be unset. + * A state proof SHALL be available for some types of information.
+ * A state proof SHALL be available for a Record, but not a receipt, and the + * response entry for each supported "get info" query. */ message QueryHeader { /** - * A signed CryptoTransferTransaction to pay the node a fee for handling this query + * A signed `CryptoTransferTransaction` to pay query fees. + *

+ * This MUST transfer HBAR from the "payer" to the responding node account + * sufficient to pay the query fees. */ Transaction payment = 1; /** - * The requested response, asking for cost, state proof, both, or neither + * A type of query response requested. */ ResponseType responseType = 2; } diff --git a/sdk/src/main/proto/response.proto b/sdk/src/main/proto/response.proto index 62daa7fb6..2fba90cfd 100644 --- a/sdk/src/main/proto/response.proto +++ b/sdk/src/main/proto/response.proto @@ -1,13 +1,21 @@ +/** + * # Query Response + * The `Response` message is returned from a query transaction. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -62,133 +69,183 @@ import "schedule_get_info.proto"; import "get_account_details.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 query response. + * + * Each query MUST define its specific response type.
+ * Each query response MUST include both the information request and a + * `ResponseHeader`.
+ * All possible query response types MUST be listed here in a `oneof`. */ message Response { oneof response { /** - * Get all entities associated with a given key + * A response for a query requesting all accounts, claims, files, and + * smart contract instances whose associated keys include the given Key. + *

+ * > This query is no longer supported. */ GetByKeyResponse getByKey = 1; /** - * Get the IDs in the format used in transactions, given the format used in Solidity + * A response for a query requesting Contract, Account, and File + * identifiers for a smart contract, given a Solidity identifier. */ GetBySolidityIDResponse getBySolidityID = 2; /** - * Response to call a function of a smart contract instance + * A response for a _local_ call to a query function of a given smart + * contract, providing function parameter inputs as needed. + *

+ * > This call is only performed on the local node. It is _not_ a + * > network consensus result. */ ContractCallLocalResponse contractCallLocal = 3; /** - * Get the runtime code for a smart contract instance + * A response for a query requesting the current bytecode for + * a smart contract. */ ContractGetBytecodeResponse contractGetBytecodeResponse = 5; /** - * Get information about a smart contract instance + * A response for a query requesting detailed information about + * a smart contract. */ ContractGetInfoResponse contractGetInfo = 4; /** - * Get all existing records for a smart contract instance + * A response for a query requesting records of all transactions + * against the given contract in the last 25 hours. + *

+ * > This query is no longer supported. */ ContractGetRecordsResponse contractGetRecordsResponse = 6; /** - * Get the current balance in a cryptocurrency account + * A response for a query requesting the HBAR balance of an account + * or contract. */ CryptoGetAccountBalanceResponse cryptogetAccountBalance = 7; /** - * Get all the records that currently exist for transactions involving an account + * A response for a query requesting records of all "recent" + * transactions for which the specified account is the effective payer. */ CryptoGetAccountRecordsResponse cryptoGetAccountRecords = 8; /** - * Get all information about an account + * A response for a query requesting information for an account.
+ * This query includes balance, but not allowances or token + * relationships. */ CryptoGetInfoResponse cryptoGetInfo = 9; /** - * Contains a livehash associated to an account + * A response for a query requesting detail for a specific live hash + * associated to a specific account. + *

+ * > This query is no longer supported. */ CryptoGetLiveHashResponse cryptoGetLiveHash = 10; /** - * Get all the accounts that proxy stake to a given account, and how much they proxy stake + * A response for a query requesting all the accounts that are proxy + * staking to this account. + *

+ * > This query is no longer supported. */ CryptoGetStakersResponse cryptoGetProxyStakers = 11; /** - * Get the contents of a file (the bytes stored in it) + * A response for a query requesting the content of a file in the + * Hedera File Service (HFS). */ FileGetContentsResponse fileGetContents = 12; /** - * Get information about a file, such as its expiration date + * A response for a query requesting file metadata from the + * Hedera File Service (HFS). */ FileGetInfoResponse fileGetInfo = 13; /** - * Get a receipt for a transaction + * A response for a query requesting the post-consensus (final) + * result of a transaction. */ TransactionGetReceiptResponse transactionGetReceipt = 14; /** - * Get a record for a transaction + * A response for a query requesting a transaction record; the detail + * changes completed in response to a transaction. */ TransactionGetRecordResponse transactionGetRecord = 15; /** - * Get a record for a transaction (lasts 180 seconds) + * A response for a query requesting a very recent transaction record. + *

+ * > This query is no longer supported. */ TransactionGetFastRecordResponse transactionGetFastRecord = 16; /** - * Parameters of and state of a consensus topic.. + * A response for a query requesting the current state of a topic for + * the Hedera Consensus Service (HCS). */ ConsensusGetTopicInfoResponse consensusGetTopicInfo = 150; /** - * Semantic versions of Hedera Services and HAPI proto + * A response for a query requesting the deployed versions of Hedera + * Services and the API definitions in semantic version format */ NetworkGetVersionInfoResponse networkGetVersionInfo = 151; /** - * Get all information about a token + * A response for a query requesting metadata for a specific Token. */ TokenGetInfoResponse tokenGetInfo = 152; /** - * Get all information about a schedule entity + * A response for a query requesting detail for a scheduled transaction. */ ScheduleGetInfoResponse scheduleGetInfo = 153; /** - * A list of the NFTs associated with the account + * A response for a query requesting detail for a subset of individual + * non-fungible/unique tokens owned by an account.
+ * The requested tokens are selected by a list index, which is based + * on the order in which the tokens were added to the account. */ TokenGetAccountNftInfosResponse tokenGetAccountNftInfos = 154; /** - * All information about an NFT + * A response for a query requesting detail for a specific + * non-fungible/unique token selected by both token identifier and + * serial number. */ TokenGetNftInfoResponse tokenGetNftInfo = 155; /** - * A list of the NFTs for the token + * A response for a query requesting detail for a subset of individual + * non-fungible/unique tokens.
+ * The requested tokens are selected by a list index, which is based + * on the order in which the tokens were minted. */ TokenGetNftInfosResponse tokenGetNftInfos = 156; /** - * Execution times of "sufficiently recent" transactions + * A response for a query requesting the time, in nanoseconds, spent + * in direct processing for one or more recent transactions. + *

+ * > This query is no longer supported. */ NetworkGetExecutionTimeResponse networkGetExecutionTime = 157; /** - * Gets all information about an account including allowances granted by the account + * A response for a query requesting detail information + * about an account. + *

+ * This query is a privileged query and "system" account authorization + * is REQUIRED for this query. */ GetAccountDetailsResponse accountDetails = 158; } diff --git a/sdk/src/main/proto/response_code.proto b/sdk/src/main/proto/response_code.proto index 81a6bc473..978ba3b97 100644 --- a/sdk/src/main/proto/response_code.proto +++ b/sdk/src/main/proto/response_code.proto @@ -1,3 +1,14 @@ +/** + * # Response Code Enumeration + * An enumeration of possible response codes. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; @@ -23,7 +34,7 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** - * UNDOCUMENTED + * An enumeration of possible response codes. */ enum ResponseCodeEnum { /** @@ -471,12 +482,12 @@ enum ResponseCodeEnum { INVALID_INITIAL_BALANCE = 85; /** - * [Deprecated]. attempt to set negative receive record threshold + * Attempt to set negative receive record threshold */ INVALID_RECEIVE_RECORD_THRESHOLD = 86 [deprecated = true]; /** - * [Deprecated]. attempt to set negative send record threshold + * Attempt to set negative send record threshold */ INVALID_SEND_RECORD_THRESHOLD = 87 [deprecated = true]; @@ -1115,7 +1126,7 @@ enum ResponseCodeEnum { UNEXPECTED_TOKEN_DECIMALS = 283; /** - * [Deprecated] The proxy account id is invalid or does not exist. + * The proxy account id is invalid or does not exist. */ INVALID_PROXY_ACCOUNT_ID = 284 [deprecated = true]; @@ -1152,7 +1163,7 @@ enum ResponseCodeEnum { NEGATIVE_ALLOWANCE_AMOUNT = 290; /** - * [Deprecated] The approveForAll flag cannot be set for a fungible token. + * The approveForAll flag cannot be set for a fungible token. */ CANNOT_APPROVE_FOR_ALL_FUNGIBLE_COMMON = 291 [deprecated = true]; @@ -1178,13 +1189,13 @@ enum ResponseCodeEnum { EMPTY_ALLOWANCES = 295; /** - * [Deprecated] Spender is repeated more than once in Crypto or Token or NFT allowance lists in a single + * Spender is repeated more than once in Crypto or Token or NFT allowance lists in a single * CryptoApproveAllowance transaction. */ SPENDER_ACCOUNT_REPEATED_IN_ALLOWANCES = 296 [deprecated = true]; /** - * [Deprecated] Serial numbers are repeated in nft allowance for a single spender account + * Serial numbers are repeated in nft allowance for a single spender account */ REPEATED_SERIAL_NUMS_IN_NFT_ALLOWANCES = 297 [deprecated = true]; @@ -1438,7 +1449,9 @@ enum ResponseCodeEnum { /** * A transaction failed because the TLS certificate provided for the - * node is missing or invalid.
+ * node is missing or invalid. + *

+ * #### Probable Causes * The certificate MUST be a TLS certificate of a type permitted for gossip * signatures.
* The value presented MUST be a UTF-8 NFKD encoding of the TLS @@ -1450,7 +1463,9 @@ enum ResponseCodeEnum { /** * A transaction failed because the hash provided for the gRPC certificate - * is present but invalid.
+ * is present but invalid. + *

+ * #### Probable Causes * The `grpc_certificate_hash` MUST be a SHA-384 hash.
* The input hashed MUST be a UTF-8 NFKD encoding of the actual TLS * certificate.
@@ -1536,17 +1551,18 @@ enum ResponseCodeEnum { TOKEN_HAS_NO_METADATA_OR_SUPPLY_KEY = 360; /** - * The transaction attempted to the use an empty List of `PendingAirdropId`. + * The list of `PendingAirdropId`s is empty and MUST NOT be empty. */ EMPTY_PENDING_AIRDROP_ID_LIST = 361; /** - * The transaction attempted to the same `PendingAirdropId` twice. + * A `PendingAirdropId` is repeated in a `claim` or `cancel` transaction. */ PENDING_AIRDROP_ID_REPEATED = 362; /** - * The transaction attempted to use more than the allowed number of `PendingAirdropId`. + * The number of `PendingAirdropId` values in the list exceeds the maximum + * allowable number. */ PENDING_AIRDROP_ID_LIST_TOO_LONG = 363; @@ -1557,8 +1573,9 @@ enum ResponseCodeEnum { /* * The identified account is sender for one or more pending airdrop(s) - * and cannot be deleted.
- * Requester should cancel all pending airdrops before resending + * and cannot be deleted. + *

+ * The requester SHOULD cancel all pending airdrops before resending * this transaction. */ ACCOUNT_HAS_PENDING_AIRDROPS = 365; @@ -1589,8 +1606,8 @@ enum ResponseCodeEnum { * The token might be deleted, or the sender may not have enough tokens * to fulfill the offer. *

- * The client SHOULD query mirror node to determine the status of the pending - * airdrop and whether the sender can fulfill the offer. + * The client SHOULD query mirror node to determine the status of the + * pending airdrop and whether the sender can fulfill the offer. */ INVALID_TOKEN_IN_PENDING_AIRDROP = 369; @@ -1611,4 +1628,87 @@ enum ResponseCodeEnum { * given an explicit expiration time. */ MISSING_EXPIRY_TIME = 372; + + /** + * A contract operation attempted to schedule another transaction after it + * had already scheduled a recursive contract call. + */ + NO_SCHEDULING_ALLOWED_AFTER_SCHEDULED_RECURSION = 373; + + /** + * A contract can schedule recursive calls a finite number of times (this is + * approximately four million times with typical network configuration.) + */ + RECURSIVE_SCHEDULING_LIMIT_REACHED = 374; + + /** + * The target network is waiting for the ledger ID to be set, which is a + * side effect of finishing the network's TSS construction. + */ + WAITING_FOR_LEDGER_ID = 375; + + /** + * The provided fee exempt key list size exceeded the limit. + */ + MAX_ENTRIES_FOR_FEE_EXEMPT_KEY_LIST_EXCEEDED = 376; + + /** + * The provided fee exempt key list contains duplicated keys. + */ + FEE_EXEMPT_KEY_LIST_CONTAINS_DUPLICATED_KEYS = 377; + + /** + * The provided fee exempt key list contains an invalid key. + */ + INVALID_KEY_IN_FEE_EXEMPT_KEY_LIST = 378; + + /** + * The provided fee schedule key contains an invalid key. + */ + INVALID_FEE_SCHEDULE_KEY = 379; + + /** + * If a fee schedule key is not set when we create a topic + * we cannot add it on update. + */ + FEE_SCHEDULE_KEY_CANNOT_BE_UPDATED = 380; + + /** + * If the topic's custom fees are updated the topic SHOULD have a + * fee schedule key + */ + FEE_SCHEDULE_KEY_NOT_SET = 381; + + /** + * The fee amount is exceeding the amount that the payer + * is willing to pay. + */ + MAX_CUSTOM_FEE_LIMIT_EXCEEDED = 382; + + /** + * There are no corresponding custom fees. + */ + NO_VALID_MAX_CUSTOM_FEE = 383; + + /** + * The provided list contains invalid max custom fee. + */ + INVALID_MAX_CUSTOM_FEES = 384; + + /** + * The provided max custom fee list contains fees with + * duplicate denominations. + */ + DUPLICATE_DENOMINATION_IN_MAX_CUSTOM_FEE_LIST = 385; + + /** + * The provided max custom fee list contains fees with + * duplicate account id. + */ + DUPLICATE_ACCOUNT_ID_IN_MAX_CUSTOM_FEE_LIST = 386; + + /** + * Max custom fees list is not supported for this operation. + */ + MAX_CUSTOM_FEES_IS_NOT_SUPPORTED = 387; } diff --git a/sdk/src/main/proto/response_header.proto b/sdk/src/main/proto/response_header.proto index 56f9c3571..11d482eb0 100644 --- a/sdk/src/main/proto/response_header.proto +++ b/sdk/src/main/proto/response_header.proto @@ -1,13 +1,21 @@ +/** + * # Response Header + * A standard header for all query responses. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -30,30 +37,49 @@ 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. + * A standard header returned with every query response. + * + * The fields for `cost` or `stateProof` MAY be unset if the requested + * `ResponseType` does not request those values.
+ * The `responseType` SHALL match the request response type.
+ * The `nodeTransactionPrecheckCode` field SHALL contain the result code + * for the query. */ message ResponseHeader { /** - * Result of fee transaction precheck, saying it passed, or why it failed + * The result code for this query. + *

+ * This value SHALL indicate either success or the reason for failure. */ ResponseCodeEnum nodeTransactionPrecheckCode = 1; /** - * The requested response is repeated back here, for convenience + * The response type requested for this query. + *

+ * This SHALL be the response type requested in the query header. */ 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) + * Requested cost estimate.
+ * This is the fee that _would be_ charged if the query was executed. + *

+ * This value SHALL be set if the response type requested requires cost + * information, and SHALL NOT be set otherwise.
+ * This value SHALL include the query fee, but SHALL NOT include the + * transfer fee required to execute the fee payment transaction. */ uint64 cost = 3; /** - * The state proof for this information (if a state proof was requested, and is available) + * A state proof for the information requested. + * + * This field SHALL NOT be set if the response type does not require + * a state proof.
+ * This field SHALL NOT be set if a state proof is not available for + * the query type.
+ * This field SHALL be set if the response type requested a state proof + * and a state proof is available. */ bytes stateProof = 4; } diff --git a/sdk/src/main/proto/roster.proto b/sdk/src/main/proto/roster.proto index e8f8c2429..ad6a61ce5 100644 --- a/sdk/src/main/proto/roster.proto +++ b/sdk/src/main/proto/roster.proto @@ -1,6 +1,6 @@ syntax = "proto3"; -package com.hedera.hashgraph.hapi.node.state.roster; +package com.hedera.hapi.node.state.roster; /* * Copyright (C) 2024 Hedera Hashgraph, LLC @@ -30,7 +30,6 @@ option java_multiple_files = true; * The roster SHALL be a list of `RosterEntry` objects. */ message Roster { - /** * List of roster entries, one per consensus node. *

diff --git a/sdk/src/main/proto/roster_state.proto b/sdk/src/main/proto/roster_state.proto index d1577f0e9..2793a3699 100644 --- a/sdk/src/main/proto/roster_state.proto +++ b/sdk/src/main/proto/roster_state.proto @@ -1,6 +1,6 @@ syntax = "proto3"; -package com.hedera.hashgraph.hapi.node.state.roster; +package com.hedera.hapi.node.state.roster; /* * Copyright (C) 2024 Hedera Hashgraph, LLC @@ -18,8 +18,6 @@ package com.hedera.hashgraph.hapi.node.state.roster; * limitations under the License. */ -import "basic_types.proto"; - option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; @@ -33,24 +31,23 @@ option java_multiple_files = true; * This data SHALL be used to track round numbers and the rosters used in determining the consensus.
*/ message RosterState { + /** + * The SHA-384 hash of a candidate roster. + *

+ * This is the hash of the roster that is currently being considered + * for adoption.
+ * A Node SHALL NOT, ever, have more than one candidate roster + * at the same time. + */ + bytes candidate_roster_hash = 1; - /** - * The SHA-384 hash of a candidate roster. - *

- * This is the hash of the roster that is currently being considered - * for adoption.
- * A Node SHALL NOT, ever, have more than one candidate roster - * at the same time. - */ - bytes candidate_roster_hash = 1; - - /** - * A list of round numbers and roster hashes.
- * The round number indicates the round in which the corresponding roster became active - *

- * This list SHALL be ordered by round numbers in descending order. - */ - repeated RoundRosterPair round_roster_pairs = 2; + /** + * A list of round numbers and roster hashes.
+ * The round number indicates the round in which the corresponding roster became active + *

+ * This list SHALL be ordered by round numbers in descending order. + */ + repeated RoundRosterPair round_roster_pairs = 2; } /** @@ -60,18 +57,17 @@ message RosterState { * active roster used for that round. */ message RoundRosterPair { + /** + * The round number. + *

+ * This value SHALL be the round number of the consensus round in which this roster became active. + */ + uint64 round_number = 1; - /** - * The round number. - *

- * This value SHALL be the round number of the consensus round in which this roster became active. - */ - uint64 round_number = 1; - - /** - * The SHA-384 hash of the active roster for the given round number. - *

- * This value SHALL be the hash of the active roster used for the round. - */ - bytes active_roster_hash = 2; + /** + * The SHA-384 hash of the active roster for the given round number. + *

+ * This value SHALL be the hash of the active roster used for the round. + */ + bytes active_roster_hash = 2; } diff --git a/sdk/src/main/proto/running_hashes.proto b/sdk/src/main/proto/running_hashes.proto index 856de26b8..36440d7d5 100644 --- a/sdk/src/main/proto/running_hashes.proto +++ b/sdk/src/main/proto/running_hashes.proto @@ -1,13 +1,21 @@ +/** + * # Running Hashes + * The running hash values for the record stream, including current and + * three(3) previous values. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,24 +34,30 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** - * The running hash of a transaction records and the previous 3 running hashes. All hashes are 48 bytes SHA384 hashes. If the - * running hashes do not exist yet then they will be default values witch is empty bytes object or zero length byte array. + * The running hash of transaction records and the previous `3` running hashes. + * + * All hashes are 48 byte SHA384 hash values. If the running hashes do not + * exist yet (for example, at genesis) then each not-yet-available value SHALL + * be empty (zero-length) bytes. */ message RunningHashes { - /** - * A running hash of all record stream items - */ - bytes running_hash = 1; - /** - * The previous running hash of all record stream items - */ - bytes n_minus_1_running_hash = 2; - /** - * The previous, previous running hash of all record stream items - */ - bytes n_minus_2_running_hash = 3; - /** - * The previous, previous, previous running hash of all record stream items - */ - bytes n_minus_3_running_hash = 4; + /** + * A running hash of all record stream items. + */ + bytes running_hash = 1; + + /** + * The previous running hash of all record stream items. + */ + bytes n_minus_1_running_hash = 2; + + /** + * The previous, previous running hash of all record stream items. + */ + bytes n_minus_2_running_hash = 3; + + /** + * The previous, previous, previous running hash of all record stream items. + */ + bytes n_minus_3_running_hash = 4; } diff --git a/sdk/src/main/proto/schedulable_transaction_body.proto b/sdk/src/main/proto/schedulable_transaction_body.proto index 6b82c18be..8191bc709 100644 --- a/sdk/src/main/proto/schedulable_transaction_body.proto +++ b/sdk/src/main/proto/schedulable_transaction_body.proto @@ -1,3 +1,16 @@ +/** + * # Schedulable Transaction Body + * A message that replicates the `TransactionBody` message, with slight + * changes to exclude fields that cannot be scheduled via a `scheduleCreate` + * transaction. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; @@ -78,269 +91,331 @@ import "node_update.proto"; import "node_delete.proto"; /** - * A schedulable transaction. Note that the global/dynamic system property - * scheduling.whitelist controls which transaction types may be scheduled. As of Hedera - * Services 0.24.0 this list includes ConsensusSubmitMessage, CryptoTransfer, TokenMint, and TokenBurn - * functions. + * A schedulable transaction. + * + * The network configuration `scheduling.whitelist` limits which of these + * transaction types may actually be scheduled. As of version `0.50.0` of the + * consensus node software this list contains only `CryptoTransfer`, + * `ConsensusSubmitMessage`, `TokenBurn`, `TokenMint`, + * and `CryptoApproveAllowance`. */ message SchedulableTransactionBody { - /** - * 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; - - /** - * The choices here are arranged by service in roughly lexicographical order. The field ordinals are non-sequential, and a result of the historical order of implementation. - */ - oneof data { - /** - * 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; - - /** - * Adds one or more approved allowances for spenders to transfer the paying account's hbar or tokens. - */ - CryptoApproveAllowanceTransactionBody cryptoApproveAllowance = 37; - - /** - * Deletes one or more of the specific approved NFT serial numbers on an owner account. - */ - CryptoDeleteAllowanceTransactionBody cryptoDeleteAllowance = 38; - - /** - * 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; - - /** - * Updates a token's custom fee schedule - */ - TokenFeeScheduleUpdateTransactionBody token_fee_schedule_update = 39; - - /** - * Pauses the Token - */ - TokenPauseTransactionBody token_pause = 35; - - /** - * Unpauses the Token - */ - TokenUnpauseTransactionBody token_unpause = 36; - - /** - * Marks a schedule in the network's action queue as deleted, preventing it from executing - */ - ScheduleDeleteTransactionBody scheduleDelete = 34; - - /** - * Generates a pseudorandom number. - */ - UtilPrngTransactionBody util_prng = 40; - - /** - * Update the metadata of one or more NFT's of a specific token type. - */ - TokenUpdateNftsTransactionBody token_update_nfts = 41; - - /** - * Transaction body for a scheduled transaction to create a new node. - */ - com.hedera.hashgraph.hapi.node.addressbook.NodeCreateTransactionBody nodeCreate = 42; - - /** - * Transaction body for a scheduled transaction to modify an existing node. - */ - com.hedera.hashgraph.hapi.node.addressbook.NodeUpdateTransactionBody nodeUpdate = 43; - - /** - * Transaction body for a scheduled transaction to remove a node. - */ - com.hedera.hashgraph.hapi.node.addressbook.NodeDeleteTransactionBody nodeDelete = 44; - - /** - * A transaction body to "reject" undesired tokens.
- * This transaction will transfer one or more tokens or token - * balances held by the requesting account to the treasury - * for each token type. + * A limit for the transaction fee the client is willing to pay. *

- * Each transfer MUST be one of the following: - *

    - *
  • A single non-fungible/unique token.
    • - *
  • The full balance held for a fungible/common - * token type.
    • - *
- * When complete, the requesting account SHALL NOT hold the - * rejected tokens.
- * Custom fees and royalties defined for the tokens rejected - * SHALL NOT be charged for this transaction. + * The network SHALL NOT charge fees greater than this value. */ - TokenRejectTransactionBody tokenReject = 45; + uint64 transactionFee = 1; /** - * Transaction body for a scheduled transaction to cancel an airdrop. - */ - TokenCancelAirdropTransactionBody tokenCancelAirdrop = 46; - - /** - * Transaction body for a scheduled transaction to claim an airdrop. - */ - TokenClaimAirdropTransactionBody tokenClaimAirdrop = 47; - - /** - * Transaction body for a scheduled transaction to airdrop tokens. - */ - TokenAirdropTransactionBody tokenAirdrop = 48; - } + * A short description of the schedulable transaction. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. + */ + string memo = 2; + + oneof data { + /** + * Call a function defined on a smart contract. + */ + ContractCallTransactionBody contractCall = 3; + + /** + * Create a smart contract. + */ + ContractCreateTransactionBody contractCreateInstance = 4; + + /** + * Update a smart contract. + */ + ContractUpdateTransactionBody contractUpdateInstance = 5; + + /** + * Delete a smart contract and transfer remaining balance + * to a specified account. + */ + ContractDeleteTransactionBody contractDeleteInstance = 6; + + /** + * Create a new Hedera account. + */ + CryptoCreateTransactionBody cryptoCreateAccount = 7; + + /** + * Delete an Hedera account.
+ * This will mark the account as deleted, and transfer all remaining + * HBAR to a receiver account. + */ + CryptoDeleteTransactionBody cryptoDelete = 8; + + /** + * Transfer HBAR between accounts. + */ + CryptoTransferTransactionBody cryptoTransfer = 9; + + /** + * Modify an Hedera account. + */ + CryptoUpdateTransactionBody cryptoUpdateAccount = 10; + + /** + * Append data to the end of a file. + */ + FileAppendTransactionBody fileAppend = 11; + + /** + * Create a new file. + */ + FileCreateTransactionBody fileCreate = 12; + + /** + * Delete a file.
+ * This will remove the content of the file, and mark the file as + * deleted. + */ + FileDeleteTransactionBody fileDelete = 13; + + /** + * Modify a file.
+ * This may modify any metadata, and/or _replace_ the content. + */ + FileUpdateTransactionBody fileUpdate = 14; + + /** + * Delete a file as an Hedera administrative function.
+ * This is a privileged operation. + */ + SystemDeleteTransactionBody systemDelete = 15; + + /** + * Restore a file deleted via `systemDelete`.
+ * This is a privileged operation. + */ + SystemUndeleteTransactionBody systemUndelete = 16; + + /** + * Freeze the network.
+ * This is actually several possible operations, and the caller + * should examine the "freeze service" for more detail.
+ * This is a privileged operation. + */ + FreezeTransactionBody freeze = 17; + + /** + * Create a topic. + */ + ConsensusCreateTopicTransactionBody consensusCreateTopic = 18; + + /** + * Update a topic. + */ + ConsensusUpdateTopicTransactionBody consensusUpdateTopic = 19; + + /** + * Delete a topic. + */ + ConsensusDeleteTopicTransactionBody consensusDeleteTopic = 20; + + /** + * Submit a message to a topic.
+ * A message may be "chunked", and submitted in parts, if the total + * message size exceeds the limit for a single transaction. + */ + ConsensusSubmitMessageTransactionBody consensusSubmitMessage = 21; + + /** + * Create a new Hedera token. + */ + TokenCreateTransactionBody tokenCreation = 22; + + /** + * Freeze an account with respect to a token.
+ * A frozen account cannot transact in that token until unfrozen. + */ + TokenFreezeAccountTransactionBody tokenFreeze = 23; + + /** + * Unfreeze an account with respect to a token. + */ + TokenUnfreezeAccountTransactionBody tokenUnfreeze = 24; + + /** + * Grant KYC to an account with respect to a token.
+ * KYC is generally a "know your customer" assertion that a + * responsible entity has sufficient information to positively + * identify the account holder to relevant authorities. + */ + TokenGrantKycTransactionBody tokenGrantKyc = 25; + + /** + * Revoke KYC from an account with respect to a token. + */ + TokenRevokeKycTransactionBody tokenRevokeKyc = 26; + + /** + * Deletes an Hedera token.
+ * The token will be marked deleted. + */ + TokenDeleteTransactionBody tokenDeletion = 27; + + /** + * Update an Hedera token.
+ * Depending on what fields are to be modified, the signature + * requirements will vary. See `TokenUpdateTransactionBody` for + * further detail. + */ + TokenUpdateTransactionBody tokenUpdate = 28; + + /** + * Mint new tokens.
+ * All minted tokens will be delivered to the treasury account for + * the token type. The "mint key" for the token must sign this + * transaction. + */ + TokenMintTransactionBody tokenMint = 29; + + /** + * Burn tokens from the treasury account.
+ * The "burn key" for the token must sign this transaction. + */ + TokenBurnTransactionBody tokenBurn = 30; + + /** + * Wipe tokens from an account.
+ * This will remove a specified amount of fungible/common tokens or + * a specified list of non-fungible/unique serial numbered tokens + * of a given token type from an Hedera account. The removed tokens + * are _burned_ as if by a `tokenBurn` transaction.
+ * The "wipe key" for the token must sign this transaction. + */ + TokenWipeAccountTransactionBody tokenWipe = 31; + + /** + * Associate tokens to an account. + */ + TokenAssociateTransactionBody tokenAssociate = 32; + + /** + * Dissociate tokens from an account. + */ + TokenDissociateTransactionBody tokenDissociate = 33; + + /** + * Delete a schedule.
+ * The schedule will be marked as deleted. + */ + ScheduleDeleteTransactionBody scheduleDelete = 34; + + /** + * Pause a Token.
+ * This transaction must be signed by the "pause key" for the token. + */ + TokenPauseTransactionBody token_pause = 35; + + /** + * Unpause a Token.
+ * This transaction must be signed by the "pause key" for the token. + */ + TokenUnpauseTransactionBody token_unpause = 36; + + /** + * Add one or more approved allowances for spenders to transfer the + * paying account's hbar or tokens. + */ + CryptoApproveAllowanceTransactionBody cryptoApproveAllowance = 37; + + /** + * Delete one or more approvals for spenders to transfer the + * paying account's hbar or tokens. + */ + CryptoDeleteAllowanceTransactionBody cryptoDeleteAllowance = 38; + + /** + * Update the custom fee schedule for a token.
+ * This transaction must be signed by the "fee schedule key" + * for the token. + */ + TokenFeeScheduleUpdateTransactionBody token_fee_schedule_update = 39; + + /** + * Provide a deterministic pseudorandom number based on network state. + */ + UtilPrngTransactionBody util_prng = 40; + + /** + * Update one or more non-fungible/unique tokens.
+ * This will update metadata for one or more serial numbers within + * a collection (token type). + */ + TokenUpdateNftsTransactionBody token_update_nfts = 41; + + /** + * Create a new node in the network address book.
+ * This is a privileged operation. + */ + com.hedera.hapi.node.addressbook.NodeCreateTransactionBody nodeCreate = 42; + + /** + * Update a node in the network address book.
+ * This is a privileged operation. + */ + com.hedera.hapi.node.addressbook.NodeUpdateTransactionBody nodeUpdate = 43; + + /** + * Delete a node from the network address book.
+ * This will mark the node as deleted.
+ * This is a privileged operation. + */ + com.hedera.hapi.node.addressbook.NodeDeleteTransactionBody nodeDelete = 44; + + /** + * "Reject" undesired tokens.
+ * This transaction will transfer one or more tokens or token + * balances held by the requesting account to the treasury + * for each token type. + *

+ * Each transfer MUST be one of the following: + *

    + *
  • A single non-fungible/unique token.
    • + *
  • The full balance held for a fungible/common + * token type.
    • + *
+ * When complete, the requesting account SHALL NOT hold the + * rejected tokens.
+ * Custom fees and royalties defined for the tokens rejected + * SHALL NOT be charged for this transaction. + */ + TokenRejectTransactionBody tokenReject = 45; + + /** + * Cancel an "airdrop".
+ * This transaction cancels a pending airdrop for one or more + * recipients. + *

+ * The airdrop(s) to cancel MUST be pending, and not claimed.
+ */ + TokenCancelAirdropTransactionBody tokenCancelAirdrop = 46; + + /** + * Claim an "airdrop". + * This transaction "claims" one or more pending "airdrops". + *

+ * The airdrop(s) to claim MUST be pending, and not + * already claimed.
+ */ + TokenClaimAirdropTransactionBody tokenClaimAirdrop = 47; + + /** + * Send an "airdrop" of tokens to one or more recipients. + *

+ * This transaction unilaterally "gifts" tokens by transferring them + * from a "sender" account to the "recipient" account(s). If any + * recipient is not already associated to the token to airdrop, or + * has set a "reciever signature required" flag, then that recipient + * is recorded as a "pending" airdrop which must be "claimed". All + * other recipients receive the "airdropped" tokens immediately. + */ + TokenAirdropTransactionBody tokenAirdrop = 48; + } } diff --git a/sdk/src/main/proto/schedule.proto b/sdk/src/main/proto/schedule.proto index b8abb6c9e..11cbc2e3e 100644 --- a/sdk/src/main/proto/schedule.proto +++ b/sdk/src/main/proto/schedule.proto @@ -1,12 +1,19 @@ +/** + * # Scheduled Transaction + * Information regarding Scheduled Transactions. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * - * Hedera Network Services Protobuf - * - * Copyright (C) 2023 Hedera Hashgraph, LLC +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -19,132 +26,189 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * */ import "basic_types.proto"; import "timestamp.proto"; import "schedulable_transaction_body.proto"; -import "transaction_body.proto"; +import "transaction.proto"; option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; /** - * Representation of a Hedera Schedule entry in the network Merkle tree. - * - * As with all network entities, a schedule has a unique entity number, which is usually given along - * with the network's shard and realm in the form of a shard.realm.number id. + * Representation of a Hedera Schedule entry in the network Merkle tree.
+ * A Schedule represents a request to run a transaction _at some future time_ + * either when the `Schedule` expires (if long term schedules are enabled and + * `wait_for_expiry` is true) or as soon as the `Schedule` has gathered + * enough signatures via any combination of the `scheduleCreate` and 0 or more + * subsequent `scheduleSign` transactions. */ message Schedule { /** - * This schedule's unique ID within the global network state. + * This schedule's ID within the global network state. + *

+ * This value SHALL be unique within the network. */ ScheduleID schedule_id = 1; /** - * The schedule deleted flag - * A schedule will either be executed or deleted, but never both. + * A flag indicating this schedule is deleted. + *

+ * A schedule SHALL either be executed or deleted, but never both. */ bool deleted = 2; /** - * The schedule executed flag - * A schedule will either be executed or deleted, but never both. + * A flag indicating this schedule has executed. + *

+ * A schedule SHALL either be executed or deleted, but never both. */ bool executed = 3; /** - * The schedule flag to wait for expiration - * A schedule will be executed immediately when all necessary signatures are gathered, unless - * this flag is set. If this flag is set, the schedule will wait until the consensus time - * reaches expiration_time_provided, when signatures will again be verified, and if all - * required signatures are present at that time, the schedule will be executed. Otherwise - * the schedule will expire without execution. - * Note that a schedule is always removed from state when it expires, regardless of whether it - * was executed or not. + * A schedule flag to wait for expiration before executing. + *

+ * A schedule SHALL be executed immediately when all necessary signatures + * are gathered, unless this flag is set.
+ * If this flag is set, the schedule SHALL wait until the consensus time + * reaches `expiration_time_provided`, when signatures MUST again be + * verified. If all required signatures are present at that time, the + * schedule SHALL be executed. Otherwise the schedule SHALL expire without + * execution. + *

+ * Note that a schedule is always removed from state after it expires, + * regardless of whether it was executed or not. */ bool wait_for_expiry = 4; /** - * The memo associated with this schedule. + * A short description for this schedule. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 5; /** - * The schedule account for this schedule. This is the account that submitted the original + * The scheduler account for this schedule. + *

+ * This SHALL be the account that submitted the original * ScheduleCreate transaction. */ AccountID scheduler_account_id = 6; /** * The explicit payer account for the scheduled transaction. - * This account is added to the accounts that must sign the schedule before it will execute. + *

+ * If set, this account SHALL be added to the accounts that MUST sign the + * schedule before it may execute. */ AccountID payer_account_id = 7; /** * The admin key for this schedule. - * If this is not set, then the schedule cannot be deleted. + *

+ * This key, if set, MUST sign any `schedule_delete` transaction.
+ * If not set, then this schedule SHALL NOT be deleted, and any + * `schedule_delete` transaction for this schedule SHALL fail. */ Key admin_key = 8; /** - * The transaction valid start value from the transaction that created this schedule. + * The transaction valid start value for this schedule. + *

+ * This MUST be set, and SHALL be copied from the `TransactionID` of + * the original `schedule_create` transaction. */ Timestamp schedule_valid_start = 9; /** - * The requested expiration time of the schedule as provided by the user. - * The actual calculated expiration time may be "earlier" than this, but will not be later. + * The requested expiration time of the schedule if provided by the user. + *

+ * If not provided in the `schedule_create` transaction, this SHALL be set + * to a default value equal to the current consensus time, forward offset by + * the maximum schedule expiration time in the current dynamic network + * configuration (typically 62 days).
+ * The actual `calculated_expiration_second` MAY be "earlier" than this, + * but MUST NOT be later. */ int64 provided_expiration_second = 10; /** - * The calculated expiration time of the schedule. This is calculated based on the requested - * expiration time from the create transaction, and the maximum expiration permitted by the - * network. - * The schedule will be removed from global network state after the network reaches a consensus - * time greater than or equal to this value. + * The calculated expiration time of the schedule. + *

+ * This SHALL be calculated from the requested expiration time in the + * `schedule_create` transaction, and limited by the maximum expiration time + * in the current dynamic network configuration (typically 62 days). + *

+ * The schedule SHALL be removed from global network state after the network + * reaches a consensus time greater than or equal to this value. */ int64 calculated_expiration_second = 11; /** * The consensus timestamp of the transaction that executed or deleted this schedule. + *

+ * This value SHALL be set to the `current_consensus_time` when a + * `schedule_delete` transaction is completed.
+ * This value SHALL be set to the `current_consensus_time` when the + * scheduled transaction is executed, either as a result of gathering the + * final required signature, or, if long-term schedule execution is enabled, + * at the requested execution time. */ Timestamp resolution_time = 12; /** * The scheduled transaction to execute. + *

+ * This MUST be one of the transaction types permitted in the current value + * of the `schedule.whitelist` in the dynamic network configuration. */ SchedulableTransactionBody scheduled_transaction = 13; /** - * The full transaction that created this schedule. This is primarily used for duplicate - * schedule create detection. This is also the source of the parent transaction ID, from - * which the child transaction ID is derived. + * The full transaction that created this schedule. + *

+ * This is primarily used for duplicate schedule create detection. This is + * also the source of the parent transaction ID, from which the child + * transaction ID is derived when the `scheduled_transaction` is executed. */ TransactionBody original_create_transaction = 14; /** - * All the primitive keys that have already signed this schedule. - * The scheduled transaction will not be executed before this list is - * sufficient to "activate" the required keys for the scheduled transaction. + * All of the "primitive" keys that have already signed this schedule. + *

+ * The scheduled transaction SHALL NOT be executed before this list is + * sufficient to "activate" the required keys for the scheduled transaction.
+ * A Key SHALL NOT be stored in this list unless the corresponding private + * key has signed either the original `schedule_create` transaction or a + * subsequent `schedule_sign` transaction intended for, and referencing to, + * this specific schedule. + *

+ * The only keys stored are "primitive" keys (ED25519 or ECDSA_SECP256K1) in + * order to ensure that any key list or threshold keys are correctly handled, + * regardless of signing order, intervening changes, or other situations. + * The `scheduled_transaction` SHALL execute only if, at the time of + * execution, this list contains sufficient public keys to satisfy the + * full requirements for signature on that transaction. */ repeated Key signatories = 15; } /** - * A message for storing a list of schedules in state. - * This is used to store lists of schedules that expire at a particular time or that have the same - * simplified hash code. + * A message for storing a list of schedules in state.
+ * This is used to store lists of `Schedule` values. + * One example is all schedules that expire at a particular time. */ message ScheduleList { - /** - * a list of schedules, in no particular order. - */ - repeated Schedule schedules = 1; + /** + * a list of schedules, in no particular order. + *

+ * While the order is not _specified_, it MUST be deterministic. + */ + repeated Schedule schedules = 1; } /** @@ -153,40 +217,52 @@ message ScheduleList { * One example is all schedules that expire at a particular time. */ message ScheduleIdList { - /** - * A list of schedule identifiers, in no particular order. - *

- * While the order is not _specified_, it MUST be deterministic. - */ - repeated ScheduleID schedule_ids = 1; + /** + * A list of schedule identifiers, in no particular order. + *

+ * While the order is not _specified_, it MUST be deterministic. + */ + repeated ScheduleID schedule_ids = 1; } /** - * The value of a map summarizing the counts of scheduled and processed transactions + * A count of schedules scheduled and processed. + * This value summarizes the counts of scheduled and processed transactions * within a particular consensus second. */ message ScheduledCounts { /** - * The number of transactions scheduled to expire at a consensus second. + * A number of transactions scheduled to expire at a consensus second. */ uint32 number_scheduled = 1; + /** - * The number of scheduled transactions that have been processed at a consensus second. + * A number of scheduled transactions that have been processed at + * a consensus second. */ uint32 number_processed = 2; } /** - * A key mapping to a particular ScheduleID that will execute at a given order number - * within a given consensus second. + * An ordering for a scheduled transaction.
+ * This establishes the order in which scheduled transactions intended to + * execute at a particular consensus second will be executed. + * + * Scheduled transactions that have the same `expiry_second` SHALL execute + * in ascending order of `order_number`. */ message ScheduledOrder { /** - * The consensus second in which the transaction is expired. + * A consensus second in which the transaction is to be executed. + * This is _also_ the consensus time when the transaction will expire + * if it has not gathered enough signatures in time. */ uint64 expiry_second = 1; + /* - * The ordered position within the consensus second that the transaction will be executed. + * An ordered position within a conceptual list.
+ * This is the ordered position within the consensus second when + * the associated transaction will be executed. */ uint32 order_number = 2; } diff --git a/sdk/src/main/proto/schedule_create.proto b/sdk/src/main/proto/schedule_create.proto index d07181711..535347968 100644 --- a/sdk/src/main/proto/schedule_create.proto +++ b/sdk/src/main/proto/schedule_create.proto @@ -1,13 +1,25 @@ +/** + * # Schedule Create + * Message to create a schedule, which is an instruction to execute some other + * transaction (the scheduled transaction) at a future time, either when + * enough signatures are gathered (short term) or when the schedule expires + * (long term). In all cases the scheduled transaction is not executed if + * signature requirements are not met before the schedule expires. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +31,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,104 +42,140 @@ import "timestamp.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 schedule's signing - * requirements, the schedule can be executed. - * - * If Long Term Scheduled Transactions are enabled and wait_for_expiry is set to true, then the schedule - * will execute at it's expiration_time. - * - * Otherwise it will execute immediately after the transaction that provided enough Ed25519 keys, a ScheduleCreate - * or ScheduleSign. - * - * 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 controlled by it's expiration_time. It remains in state and can be queried - * using GetScheduleInfo until expiration, no matter if the scheduled transaction has - * executed or marked deleted. If Long Term Scheduled Transactions are disabled, the expiration_time is always - * 30 minutes in the future. + * Create a new Schedule. * - * 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. + * #### Requirements + * This transaction SHALL create a new _schedule_ entity in network state.
+ * The schedule created SHALL contain the `scheduledTransactionBody` to be + * executed.
+ * If successful the receipt SHALL contain a `scheduleID` with the full + * identifier of the schedule created.
+ * When a schedule _executes_ successfully, the receipt SHALL include a + * `scheduledTransactionID` with the `TransactionID` of the transaction that + * executed.
+ * When a scheduled transaction is executed the network SHALL charge the + * regular _service_ fee for the transaction to the `payerAccountID` for + * that schedule, but SHALL NOT charge node or network fees.
+ * If the `payerAccountID` field is not set, the effective `payerAccountID` + * SHALL be the `payer` for this create transaction.
+ * If an `adminKey` is not specified, or is an empty `KeyList`, the schedule + * created SHALL be immutable.
+ * An immutable schedule MAY be signed, and MAY execute, but SHALL NOT be + * deleted.
+ * If two schedules have the same values for all fields except `payerAccountID` + * then those two schedules SHALL be deemed "identical".
+ * If a `scheduleCreate` requests a new schedule that is identical to an + * existing schedule, the transaction SHALL fail and SHALL return a status + * code of `IDENTICAL_SCHEDULE_ALREADY_CREATED` in the receipt.
+ * The receipt for a duplicate schedule SHALL include the `ScheduleID` of the + * existing schedule and the `TransactionID` of the earlier `scheduleCreate` + * so that the earlier schedule may be queried and/or referred to in a + * subsequent `scheduleSign`. * - * When a scheduledTransactionBody 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. + * #### Signature Requirements + * A `scheduleSign` transaction SHALL be used to add additional signatures + * to an existing schedule.
+ * Each signature SHALL "activate" the corresponding cryptographic("primitive") + * key for that schedule.
+ * Signature requirements SHALL be met when the set of active keys includes + * all keys required by the scheduled transaction.
+ * A scheduled transaction for a "long term" schedule SHALL NOT execute if + * the signature requirements for that transaction are not met when the + * network consensus time reaches the schedule `expiration_time`.
+ * A "short term" schedule SHALL execute immediately once signature + * requirements are met. This MAY be immediately when created. * - * Two ScheduleCreate transactions are identical if they are equal in all their - * fields other than payerAccountID. (For the scheduledTransactionBody field, - * "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.) + * #### Long Term Schedules + * A "short term" schedule SHALL have the flag `wait_for_expiry` _unset_.
+ * A "long term" schedule SHALL have the flag `wait_for_expiry` _set_.
+ * A "long term" schedule SHALL NOT be accepted if the network configuration + * `scheduling.longTermEnabled` is not enabled.
+ * A "long term" schedule SHALL execute when the current consensus time + * matches or exceeds the `expiration_time` for that schedule, if the + * signature requirements for the scheduled transaction + * are met at that instant.
+ * A "long term" schedule SHALL NOT execute before the current consensus time + * matches or exceeds the `expiration_time` for that schedule.
+ * A "long term" schedule SHALL expire, and be removed from state, after the + * network consensus time exceeds the schedule `expiration_time`.
+ * A short term schedule SHALL expire, and be removed from state, + * after the network consensus time exceeds the current network + * configuration for `ledger.scheduleTxExpiryTimeSecs`. * - * 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.) + * > Note + * >> Long term schedules are not (as of release 0.56.0) enabled. Any schedule + * >> created currently MUST NOT set the `wait_for_expiry` flag.
+ * >> When long term schedules are not enabled, schedules SHALL NOT be + * >> executed at expiration, and MUST meet signature requirements strictly + * >> before expiration to be executed. * - * 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. + * ### Block Stream Effects + * If the scheduled transaction is executed immediately, the transaction + * record SHALL include a `scheduleRef` with the schedule identifier of the + * schedule created. */ message ScheduleCreateTransactionBody { - /** - * The scheduled transaction - */ - SchedulableTransactionBody scheduledTransactionBody = 1; + /** + * A scheduled transaction. + *

+ * This value is REQUIRED.
+ * This transaction body MUST be one of the types enabled in the + * network configuration value `scheduling.whitelist`. + */ + SchedulableTransactionBody scheduledTransactionBody = 1; - /** - * An optional memo with a UTF-8 encoding of no more than 100 bytes which does not contain the - * zero byte - */ - string memo = 2; + /** + * A short description of the schedule. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. + */ + string memo = 2; - /** - * An optional Hedera key which can be used to sign a ScheduleDelete and remove the schedule - */ - Key adminKey = 3; + /** + * A `Key` required to delete this schedule. + *

+ * If this is not set, or is an empty `KeyList`, this schedule SHALL be + * immutable and SHALL NOT be deleted. + */ + Key adminKey = 3; - /** - * 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; + /** + * An account identifier of a `payer` for the scheduled transaction. + *

+ * This value MAY be unset. If unset, the `payer` for this `scheduleCreate` + * transaction SHALL be the `payer` for the scheduled transaction.
+ * If this is set, the identified account SHALL be charged the fees + * required for the scheduled transaction when it is executed.
+ * If the actual `payer` for the _scheduled_ transaction lacks + * sufficient HBAR balance to pay service fees for the scheduled + * transaction _when it executes_, the scheduled transaction + * SHALL fail with `INSUFFICIENT_PAYER_BALANCE`.
+ */ + AccountID payerAccountID = 4; - /** - * An optional timestamp for specifying when the transaction should be evaluated for execution and then expire. - * Defaults to 30 minutes after the transaction's consensus timestamp. - * - * Note: This field is unused and forced to be unset until Long Term Scheduled Transactions are enabled - Transactions will always - * expire in 30 minutes if Long Term Scheduled Transactions are not enabled. - */ - Timestamp expiration_time = 5; + /** + * An expiration time. + *

+ * If not set, the expiration SHALL default to the current consensus time + * advanced by either the network configuration value + * `scheduling.maxExpirationFutureSeconds`, if `wait_for_expiry` is set and + * "long term" schedules are enabled, or the network configuration value + * `ledger.scheduleTxExpiryTimeSecs` otherwise. + */ + Timestamp expiration_time = 5; - /** - * When set to true, the transaction will be evaluated for execution at expiration_time instead - * of when all required signatures are received. - * When set to false, the transaction will execute immediately after sufficient signatures are received - * to sign the contained transaction. During the initial ScheduleCreate transaction or via ScheduleSign transactions. - * - * Defaults to false. - * - * Setting this to false does not necessarily mean that the transaction will never execute at expiration_time. - * For Example - If the signature requirements for a Scheduled Transaction change via external means (e.g. CryptoUpdate) - * such that the Scheduled Transaction would be allowed to execute, it will do so autonomously at expiration_time, unless a - * ScheduleSign comes in to "poke" it and force it to go through immediately. - * - * Note: This field is unused and forced to be unset until Long Term Scheduled Transactions are enabled. Before Long Term - * Scheduled Transactions are enabled, Scheduled Transactions will _never_ execute at expiration - they will _only_ - * execute during the initial ScheduleCreate transaction or via ScheduleSign transactions and will _always_ - * expire at expiration_time. - */ - bool wait_for_expiry = 13; + /** + * A flag to delay execution until expiration. + *

+ * If this flag is set the scheduled transaction SHALL NOT be evaluated for + * execution before the network consensus time matches or exceeds the + * `expiration_time`.
+ * If this flag is not set, the scheduled transaction SHALL be executed + * immediately when all required signatures are received, whether in this + * `scheduleCreate` transaction or a later `scheduleSign` transaction.
+ * This value SHALL NOT be used and MUST NOT be set when the network + * configuration value `scheduling.longTermEnabled` is not enabled. + */ + bool wait_for_expiry = 13; } diff --git a/sdk/src/main/proto/schedule_delete.proto b/sdk/src/main/proto/schedule_delete.proto index b5985d3a3..8c780a4a3 100644 --- a/sdk/src/main/proto/schedule_delete.proto +++ b/sdk/src/main/proto/schedule_delete.proto @@ -1,13 +1,21 @@ +/** + * # Schedule Delete + * A transaction body for a `scheduleDelete` transaction. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,18 +36,24 @@ 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. + * Mark a schedule in the network state as deleted. + * + * This transaction MUST be signed by the `adminKey` for the + * identified schedule.
+ * If a schedule does not have `adminKey` set or if `adminKey` is an empty + * `KeyList`, that schedule SHALL be immutable and MUST NOT be deleted.
+ * A deleted schedule SHALL not be executed.
+ * A deleted schedule MUST NOT be the subject of a subsequent + * `scheduleSign` transaction. * - * Other notable response codes include, INVALID_SCHEDULE_ID, SCHEDULE_PENDING_EXPIRATION, - * SCHEDULE_ALREADY_DELETED, SCHEDULE_ALREADY_EXECUTED, SCHEDULE_IS_IMMUTABLE. - * For more information please see the section of this documentation on the ResponseCode - * enum. -*/ + * ### Block Stream Effects + * None + */ message ScheduleDeleteTransactionBody { /** - * The ID of the Scheduled Entity + * A schedule identifier. + *

+ * This MUST identify the schedule which SHALL be deleted. */ ScheduleID scheduleID = 1; } diff --git a/sdk/src/main/proto/schedule_get_info.proto b/sdk/src/main/proto/schedule_get_info.proto index bf987f564..cdb2ae8d7 100644 --- a/sdk/src/main/proto/schedule_get_info.proto +++ b/sdk/src/main/proto/schedule_get_info.proto @@ -1,13 +1,22 @@ +/** + * # Schedule Get Information + * Query body and response to retrieve information about a scheduled + * transaction. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -33,117 +41,199 @@ import "response_header.proto"; import "schedulable_transaction_body.proto"; /** - * Gets information about a schedule in the network's action queue. + * Request for information about a scheduled transaction. * - * Responds with INVALID_SCHEDULE_ID if the requested schedule doesn't exist. + * If the requested schedule does not exist, the network SHALL respond + * with `INVALID_SCHEDULE_ID`. */ message ScheduleGetInfoQuery { - /** - * 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; + /** + * Standard information sent with every query operation.
+ * This includes the signed payment and what kind of response is requested + * (cost, state proof, both, or neither). + */ + QueryHeader header = 1; + + /** + * A schedule identifier. + *

+ * This SHALL identify the schedule to retrieve.
+ * This field is REQUIRED. + */ + ScheduleID scheduleID = 2; } /** * Information summarizing schedule state */ message ScheduleInfo { - /** - * The id of the schedule - */ - ScheduleID scheduleID = 1; + /** + * A schedule identifier. + *

+ * This SHALL identify the schedule retrieved. + */ + ScheduleID scheduleID = 1; + + oneof data { + /** + * A deletion timestamp. + *

+ * If the schedule was deleted, this SHALL be set to the consensus + * timestamp of the `deleteSchedule` transaction.
+ * If the schedule is _not_ deleted, this field SHALL NOT be set. + */ + Timestamp deletion_time = 2; + + /** + * An execution timestamp. + *

+ * If the schedule was completed, and the _scheduled_ transaction + * executed, this SHALL be set to the consensus timestamp of the + * transaction that initiated that execution.
+ * If the schedule is _not_ complete, this field SHALL NOT be set. + */ + Timestamp execution_time = 3; + } + + /** + * An expiration timestamp.
+ * This represents the time at which the schedule will expire. For a + * long-term schedule (if enabled) this is when the schedule will be + * executed, assuming it meets signature requirements at that time. + * For a short-term schedule, this is the deadline to complete the + * signature requirements for the scheduled transaction to execute. + * Regardless of schedule type, the schedule will be removed from + * state when it expires. + *

+ * A schedule SHALL be removed from state when it expires.
+ * A short-term schedule MUST meet signature requirements strictly + * before expiration or it SHALL NOT be executed.
+ * A long-term schedule SHALL be executed if, and only if, all signature + * requirements for the scheduled transaction are met at expiration.
+ * A long-term schedule SHALL NOT be executed if any signature requirement + * for the scheduled transaction are not met at expiration.
+ */ + Timestamp expirationTime = 4; + + /** + * A scheduled transaction. + *

+ * This SHALL be a transaction type enabled in the network property + * `scheduling.whitelist`, and SHALL NOT be any other + * transaction type.
+ * This transaction SHALL be executed if the schedule meets all signature + * and execution time requirements for this transaction.
+ * The signature requirements for this transaction SHALL be evaluated + * at schedule creation, SHALL be reevaluated with each `signSchedule` + * transaction, and, for long-term schedules, SHALL be reevaluated when + * the schedule expires.
+ */ + SchedulableTransactionBody scheduledTransactionBody = 5; + + /** + * A short description for this schedule. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. + */ + string memo = 6; - oneof data { /** - * If the schedule has been deleted, the consensus time when this occurred + * The key used to delete the schedule from state */ - Timestamp deletion_time = 2; + Key adminKey = 7; /** - * If the schedule has been executed, the consensus time when this occurred + * A list of "valid" signatures for this schedule.
+ * This list contains only "primitive" (i.e. cryptographic or contract) + * signatures. The full signature requirements for the scheduled + * transaction are evaluated as if this list of keys had signed the + * scheduled transaction directly. + *

+ * This list SHALL contain every "primitive" key that has signed the + * original `createSchedule`, or any subsequent + * `signSchedule` transaction.
+ * This list MAY elide any signature not likely to be required by the + * scheduled transaction. Such requirement SHOULD be evaluated when the + * signature is presented (i.e. during evaluation of a `createSchedule` or + * `signSchedule` transaction). */ - Timestamp execution_time = 3; - } - - /** - * The time at which the schedule will be evaluated for execution and then expire. - * - * Note: Before Long Term Scheduled Transactions are enabled, Scheduled Transactions will _never_ execute at expiration - they - * will _only_ execute during the initial ScheduleCreate transaction or via ScheduleSign transactions and will _always_ - * expire at expirationTime. - */ - 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; - - /** - * The ledger ID the response was returned from; please see HIP-198 for the network-specific IDs. - */ - bytes ledger_id = 12; - - /** - * When set to true, the transaction will be evaluated for execution at expiration_time instead - * of when all required signatures are received. - * When set to false, the transaction will execute immediately after sufficient signatures are received - * to sign the contained transaction. During the initial ScheduleCreate transaction or via ScheduleSign transactions. - * - * Note: this field is unused until Long Term Scheduled Transactions are enabled. - */ - bool wait_for_expiry = 13; + KeyList signers = 8; + + /** + * An account identifier. + *

+ * This SHALL identify the account that created this schedule. + */ + AccountID creatorAccountID = 9; + + /** + * An account identifier. + *

+ * The identified account SHALL pay the full transaction fee for the + * scheduled transaction _when it executes_. + */ + AccountID payerAccountID = 10; + + /** + * A transaction identifier. + *

+ * This SHALL be recorded as the transaction identifier for the + * _scheduled_ transaction, if (and when) it is executed. + */ + TransactionID scheduledTransactionID = 11; + + /** + * The ledger ID of the network that generated this response. + *

+ * This value SHALL identify the distributed ledger that responded to + * this query. + */ + bytes ledger_id = 12; + + /** + * A flag indicating this schedule will execute when it expires. + *

+ * If this field is set + *

    + *
  • This schedule SHALL be considered a "long-term" schedule.
    • + *
  • This schedule SHALL be evaluated when the network consensus time + * reaches the `expirationTime`, and if the signature requirements + * for the scheduled transaction are met at that time, the + * scheduled transaction SHALL be executed.
    • + *
  • This schedule SHALL NOT be executed before the network consensus + * time reaches the `expirationTime`.
    • + *
+ * If this field is not set + *
    + *
  • This schedule SHALL be considered a "short-term" schedule.
    • + *
  • This schedule SHALL be evaluated when created, and reevaluated + * with each `signSchedule` transaction, and if the signature + * requirements for the scheduled transaction are met at that time, + * the scheduled transaction SHALL be executed immediately.
    • + *
  • This schedule SHALL be executed as soon as the signature + * requirements are met, and MUST be executed before the network + * consensus time reaches the `expirationTime`, if at all.
    • + *
+ */ + bool wait_for_expiry = 13; } /** - * Response wrapper for the ScheduleInfo + * A response message for a `getScheduleInfo` query. */ message ScheduleGetInfoResponse { - /** - * 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; + /** + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). + */ + ResponseHeader header = 1; + + /** + * Detail information for a schedule. + *

+ * This field SHALL contain all available schedule detail. + */ + ScheduleInfo scheduleInfo = 2; } diff --git a/sdk/src/main/proto/schedule_service.proto b/sdk/src/main/proto/schedule_service.proto index 2289f586d..97a8a5c13 100644 --- a/sdk/src/main/proto/schedule_service.proto +++ b/sdk/src/main/proto/schedule_service.proto @@ -1,13 +1,21 @@ +/** + * # Schedule Service + * gRPC service definitions for the Schedule Service. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -31,79 +38,82 @@ 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. The transactions can be executed immediately when all required signatures are received - * or at a future date if Long Term Scheduled Transactions are enabled. - * - * Execution: - * - * Scheduled Transactions are executed in two different modes. - * - * 1. If Long Term Scheduled Transactions are enabled and wait_for_expiry was set to true on the - * ScheduleCreate, then the transaction will be executed at the expiration_time specified on the - * ScheduleCreate. - * - * 2. Otherwise 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. - * - * NOTICE: - * A Scheduled Transaction being ready to execute, or even not ready to execute, at the time a ScheduleCreate or - * ScheduleSign comes in does not guarantee it will stay that way. Any number of things can happen over time that - * impact the transaction. - * - * For example, account keys can change, accounts can be deleted, and account balances can change. - * - * A particularly noteworthy case is if Long Term Scheduled Transactions are enabled and signature requirements for a Scheduled - * Transaction change such that existing signatures become sufficient to allow the transaction to go through. In this case the transaction - * will execute at expiration_time unless a ScheduleSign comes in to push it through. - * - * Transaction Record: - * - * If a Scheduled Transaction is executed immediately following the transaction that provided all required signatures, - * 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: - * - * After execution, a Scheduled Transaction will remain in state and can be queried using GetScheduleInfo until expiration. - * - * Expiry: - * - * The expiration time of a schedule is controlled by it's expiration_time. If Long Term Scheduled Transactions are disabled, - * the expiration_time is always 30 minutes in the future. - * - * Once a given Scheduled Transaction expires, it will be removed from the ledger and any upcoming - * operation referring the ScheduleID will resolve to INVALID_SCHEDULE_ID. - * + * Transactions and queries for the Schedule Service.
+ * The Schedule Service enables transactions to be submitted without all + * required signatures and offers a `scheduleSign` transaction to provide + * additional signatures independently after the schedule is created. The + * scheduled transaction may be executed immediately when all required + * signatures are present, or at expiration if "long term" schedules + * are enabled in network configuration. + * + * ### Execution + * Scheduled transactions SHALL be executed under the following conditions. + * 1. If "long term" schedules are enabled and `wait_for_expiry` is set for + * that schedule then the transaction SHALL NOT be executed before the + * network consensus time matches or exceeds the `expiration_time` field + * for that schedule. + * 1. If "long term" schedules are enabled and `wait_for_expiry` is _not_ set + * for that schedule, then the transaction SHALL be executed when all + * signatures required by the scheduled transaction are active for that + * schedule. This MAY be immediately after the `scheduleCreate` or a + * subsequent `scheduleSign` transaction, or MAY be at expiration if + * the signature requirements are met at that time. + * 1. If "long term" schedules are _disabled_, then the scheduled transaction + * SHALL be executed immediately after all signature requirements for the + * scheduled transaction are met during the `scheduleCreate` or a subsequent + * `scheduleSign` transaction. The scheduled transaction SHALL NOT be + * on expiration when "long term" schedules are disabled. + * + * A schedule SHALL remain in state and MAY be queried with a `getScheduleInfo` + * transaction after execution, until the schedule expires.
+ * When network consensus time matches or exceeds the `expiration_time` for + * a schedule, that schedule SHALL be removed from state, whether it has + * executed or not.
+ * If "long term" schedules are _disabled_, the maximum expiration time SHALL + * be the consensus time of the `scheduleCreate` transaction extended by + * the network configuration value `ledger.scheduleTxExpiryTimeSecs`. + * + * ### Block Stream Effects + * When a scheduled transaction is executed, the timestamp in the transaction + * identifier for that transaction SHALL be 1 nanosecond after the consensus + * timestamp for the transaction that resulted in its execution. If execution + * occurred at expiration, that transaction may be almost any transaction, + * including another scheduled transaction that executed at expiration.
+ * The transaction identifier for a scheduled transaction that is executed + * SHALL have the `scheduled` flag set and SHALL inherit the `accountID` and + * `transactionValidStart` values from the `scheduleCreate` that created the + * schedule.
+ * The `scheduleRef` property of the record for a scheduled transaction SHALL + * be populated with the schedule identifier of the schedule that executed. */ service ScheduleService { /** - * Creates a new Schedule by submitting the transaction + * Create a new Schedule. + *

+ * If all signature requirements are met with this transaction, the + * scheduled transaction MAY execute immediately. */ rpc createSchedule (Transaction) returns (TransactionResponse); /** - * Signs a new Schedule by submitting the transaction + * Add signatures to an existing schedule. + *

+ * Signatures on this transaction SHALL be added to the set of active + * signatures on the schedule, and MAY result in execution of the + * scheduled transaction if all signature requirements are met. */ rpc signSchedule (Transaction) returns (TransactionResponse); /** - * Deletes a new Schedule by submitting the transaction + * Mark an existing schedule deleted. + *

+ * Once deleted a schedule SHALL NOT be executed and any subsequent + * `scheduleSign` transaction SHALL fail. */ rpc deleteSchedule (Transaction) returns (TransactionResponse); /** - * Retrieves the metadata of a schedule entity + * Retrieve the metadata for a schedule. */ rpc getScheduleInfo (Query) returns (Response); } diff --git a/sdk/src/main/proto/schedule_sign.proto b/sdk/src/main/proto/schedule_sign.proto index a4191fe5f..8eff8d648 100644 --- a/sdk/src/main/proto/schedule_sign.proto +++ b/sdk/src/main/proto/schedule_sign.proto @@ -1,13 +1,22 @@ +/** + * # Schedule Sign + * Transaction body for a `scheduleSign` transaction to add signatures + * to an existing scheduled transaction. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,27 +37,36 @@ option java_multiple_files = true; import "basic_types.proto"; /** - * Adds zero or more signing keys to a schedule. - * - * If Long Term Scheduled Transactions are enabled and wait_for_expiry was set to true on the - * ScheduleCreate then the transaction will always wait till it's `expiration_time` to execute. - * - * Otherwise, if the resulting set of signing keys satisfy the - * scheduled transaction's signing requirements, it will be executed immediately after the - * triggering ScheduleSign. + * Add signatures to an existing scheduled transaction. * - * Upon SUCCESS, the receipt includes the scheduledTransactionID to use to query - * for the record of the scheduled transaction's execution (if it occurs). + * When a schedule _executes_ successfully, the receipt SHALL include a + * `scheduledTransactionID` with the `TransactionID` of the transaction that + * executed.
+ * When a scheduled transaction is executed the network SHALL charge the + * regular _service_ fee for the transaction to the `payerAccountID` for + * that schedule, but SHALL NOT charge node or network fees.
+ * If the `payerAccountID` field is not set, the effective `payerAccountID` + * SHALL be the `payer` for this create transaction.
+ * Each signature on this transaction SHALL "activate" the corresponding + * cryptographic("primitive") key for the schedule identified.
+ * Signature requirements SHALL be met when the set of active keys includes + * all keys required by the scheduled transaction.
+ * A scheduled transaction for a "long term" schedule SHALL NOT execute if + * the signature requirements for that transaction are not met when the + * network consensus time reaches the schedule `expiration_time`.
+ * A "short term" schedule SHALL execute immediately once signature + * requirements are met. This MAY be immediately when created.
* - * Other notable response codes include INVALID_SCHEDULE_ID, SCHEDULE_ALREADY_DELETED, - * SCHEDULE_PENDING_EXPIRATION, SCHEDULE_ALREADY_EXPIRED, - * 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. + * ### Block Stream Effects + * If the scheduled transaction is executed immediately following this + * `scheduleSign` transaction, the transaction record SHALL include a + * `scheduleRef` with the schedule identifier `scheduleID`. */ message ScheduleSignTransactionBody { /** - * The id of the schedule to add signing keys to + * A schedule identifier. + *

+ * This MUST identify the schedule to which signatures SHALL be added. */ ScheduleID scheduleID = 1; } diff --git a/sdk/src/main/proto/smart_contract_service.proto b/sdk/src/main/proto/smart_contract_service.proto index 84a7b2d73..bb0521822 100644 --- a/sdk/src/main/proto/smart_contract_service.proto +++ b/sdk/src/main/proto/smart_contract_service.proto @@ -1,13 +1,22 @@ +/** + * # Smart Contract Service + * gRPC service definitions for calls to the Hedera EVM-compatible + * Smart Contract service. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,8 +28,8 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ + option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package @@ -30,69 +39,151 @@ import "response.proto"; import "transaction.proto"; /** - * Transactions and queries for the file service. + * The Hedera Smart Contract Service (HSCS) provides an interface to an EVM + * compatible environment to create, store, manage, and execute smart contract + * calls. Smart Contracts implement useful and often highly complex + * interactions between individuals, systems, and the distributed ledger. */ service SmartContractService { /** - * Creates a contract + * Create a new smart contract. + *

+ * If this transaction succeeds, the `ContractID` for the new smart + * contract SHALL be set in the transaction receipt.
+ * The contract is defined by the initial bytecode (or `initcode`). + * The `initcode` SHALL be provided either in a previously created file, + * or in the transaction body itself for very small contracts.
+ * As part of contract creation, the constructor defined for the new + * smart contract SHALL run with the parameters provided in + * the `constructorParameters` field.
+ * The gas to "power" that constructor MUST be provided via the `gas` + * field, and SHALL be charged to the payer for this transaction.
+ * If the contract _constructor_ stores information, it is charged gas for + * that storage. There is a separate fee in HBAR to maintain that storage + * until the expiration, and that fee SHALL be added to this transaction + * as part of the _transaction fee_, rather than gas. */ rpc createContract (Transaction) returns (TransactionResponse); /** - * Updates a contract with the content + * Modify a smart contract.
+ * Any change other than updating the expiration time requires that the + * contract be modifiable (has a valid `adminKey`) and that the + * transaction be signed by the `adminKey` + *

+ * Fields _not set_ on the request SHALL NOT be modified. */ rpc updateContract (Transaction) returns (TransactionResponse); /** - * Calls a contract + * Call a function of a given smart contract, providing function parameter + * inputs as needed. + *

+ * Resource ("gas") charges SHALL include all relevant fees incurred by + * the contract execution, including any storage required.
+ * The total transaction fee SHALL incorporate all of the "gas" actually + * consumed as well as the standard fees for transaction handling, + * data transfers, signature verification, etc... */ rpc contractCallMethod (Transaction) returns (TransactionResponse); /** - * Retrieves the contract information + * Call a query function of a given smart contract, providing + * function parameter inputs as needed.
+ * This is performed locally on the particular node that the client is + * communicating with. Executing the call locally is faster and less + * costly, but imposes certain restrictions. + *

+ * The call MUST NOT change the state of the contract instance. This also + * precludes any expenditure or transfer of HBAR or other tokens.
+ * The call SHALL NOT have a separate consensus timestamp.
+ * The call SHALL NOT generate a record nor a receipt.
+ * The response SHALL contain the output returned by the function call.
+ *

+ * This is generally useful for calling accessor functions which read + * (query) state without changes or side effects. Any contract call that + * would use the `STATICCALL` opcode MAY be called via contract call local + * with performance and cost benefits. + *

+ * Unlike a ContractCall transaction, the node SHALL always consume the + * _entire_ amount of offered "gas" in determining the fee for this query, + * so accurate gas estimation is important. */ - rpc getContractInfo (Query) returns (Response); + rpc contractCallLocalMethod (Query) returns (Response); /** - * Calls a smart contract to be run on a single node + * A standard query to obtain detailed information for a smart contract. */ - rpc contractCallLocalMethod (Query) returns (Response); + rpc getContractInfo (Query) returns (Response); /** - * Retrieves the runtime code of a contract + * A standard query to read the current bytecode for a smart contract. */ rpc ContractGetBytecode (Query) returns (Response); /** - * Retrieves a contract by its Solidity address + * A standard query to obtain account and contract identifiers for a smart + * contract, given the Solidity identifier for that contract. */ - rpc getBySolidityID (Query) returns (Response); + rpc getBySolidityID (Query) returns (Response) {option deprecated = true;}; /** - * Always returns an empty record list, as contract accounts are never effective payers for - * transactions + *

This query is no longer supported.
+ * This query always returned an empty record list. */ - rpc getTxRecordByContractID (Query) returns (Response) { - option deprecated = true; - }; + rpc getTxRecordByContractID (Query) returns (Response) {option deprecated = true;}; /** - * Deletes a contract instance and transfers any remaining hbars to a specified receiver + * Delete a smart contract, and transfer any remaining HBAR balance + * to a designated account. + *

+ * If this call succeeds then all subsequent calls to that smart + * contract SHALL fail.
*/ rpc deleteContract (Transaction) returns (TransactionResponse); /** - * Deletes a contract if the submitting account has network admin privileges + * Delete a smart contract, as a system-initiated deletion, this + * SHALL NOT transfer balances. + *

+ * This call is an administrative function of the Hedera network, and + * SHALL require network administration authorization.
+ * This transaction MUST be signed by one of the network administration + * accounts (typically `0.0.2` through `0.0.59`, as defined in the + * `api-permission.properties` file). + *
+ * If this call succeeds then all subsequent calls to that smart + * contract SHALL fail.
*/ - rpc systemDelete (Transaction) returns (TransactionResponse); + rpc systemDelete (Transaction) returns (TransactionResponse) {option deprecated = true;}; /** - * Undeletes a contract if the submitting account has network admin privileges + * Un-Delete a smart contract, returning it (mostly) to its state + * prior to deletion. + *

+ * The contract to be restored MUST have been deleted via `systemDelete`. + * If the contract was deleted via `deleteContract`, it + * SHALL NOT be recoverable. + *

+ * This call is an administrative function of the Hedera network, and + * SHALL require network administration authorization.
+ * This transaction MUST be signed by one of the network administration + * accounts (typically `0.0.2` through `0.0.59`, as defined in the + * `api-permission.properties` file). + *
+ * If this call succeeds then subsequent calls to that smart + * contract MAY succeed.
*/ - rpc systemUndelete (Transaction) returns (TransactionResponse); + rpc systemUndelete (Transaction) returns (TransactionResponse) {option deprecated = true;}; /** - * Ethereum transaction + * Make an Ethereum transaction "call" with all data in Ethereum formats, + * including the contract alias. + *

+ * Call data MAY be in the transaction, or stored within a "File".
+ * The caller MAY offer additional gas above what is offered in the call + * data, but MAY be charged up to 80% of that value if the amount required + * is less than this "floor" amount. */ rpc callEthereum (Transaction) returns (TransactionResponse); } diff --git a/sdk/src/main/proto/staking_node_info.proto b/sdk/src/main/proto/staking_node_info.proto index 508acee94..db2beace4 100644 --- a/sdk/src/main/proto/staking_node_info.proto +++ b/sdk/src/main/proto/staking_node_info.proto @@ -1,13 +1,21 @@ +/** + * # Staking Node Information + * This is an entry describing the staking characteristics of a single active + * node. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,84 +27,143 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ -import "common.proto"; -import "basic_types.proto"; - option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; /** - * Representation of a Hedera Token Service staking info entity in the network Merkle tree. + * An Hedera Token Service staking info entity. * - * As with all network entities, staking info is per node and has a unique entity number represented as shard.realm.X. + * Staking info is per node. Shard and Realm are implied based on the network + * address book entry for this node. */ message StakingNodeInfo { /** - * The unique entity number of the node. The shard and realm numbers are implied, based on the network - * this entity came from. + * The entity number of this node.
+ * The shard and realm numbers are implied, based on the network address + * book entry for this node. + *

+ * This value SHALL be unique within a given shard and realm.
+ * This value MAY be repeated across shards and/or realms. */ int64 node_number = 1; + /** - * The minimum stake on this node that is required for this node to have a non-zero weight to - * participate in the network consensus. + * The minimum stake, in tinybar, that is required for this node to have a + * non-zero weight in the network consensus. + *

+ * If the current value of `stake` is below this value, this node SHALL have + * a zero weight in network consensus. */ int64 min_stake = 2; + /** - * The maximum stake on this node that is considered to calculate its weight to participate in the network consensus. + * The maximum stake to this node that is considered to calculate its weight + * in the network consensus. + *

+ * If the current `stake` value is above this limit, the excess staked HBAR + * SHALL NOT be considered when determining consensus weight. */ int64 max_stake = 3; + /** - * The sum of balances of all accounts staked to this node who have opted to receive rewards. + * The sum of balances of all accounts staked to this node, considering only + * accounts that choose to receive rewards. */ int64 stake_to_reward = 4; + /** - * The sum of balances of all accounts staked to this node who have opted to decline rewards. + * The sum of balances of all accounts staked to this node, considering only + * accounts that decline to receive rewards. */ int64 stake_to_not_reward = 5; + /** - * The snapshot of stake_to_reward value at the beginning of the current staking period. - * This is needed for calculating rewards for current staking period without considering changes to - * stake_to_reward in the current staking period. It is reset at the beginning of every period. + * The snapshot of stake_to_reward value at the beginning of the current + * staking period. + *

+ * This is necessary when calculating rewards for the current staking period + * without considering changes to `stake_to_reward` _within_ the current + * staking period.
+ * This value SHALL be reset at the beginning of every staking period. */ int64 stake_reward_start = 6; + /** - * Tracks how much stake from stakeRewardStart will have unclaimed rewards due to accounts changing their staking - * metadata in a way that disqualifies them for the current period; It is reset at the beginning of every period + * The amount of staked HBAR from `stake_reward_start` that will have + * unclaimed rewards due to accounts changing their staking metadata in a + * way that disqualifies them for the current staking period. + *

+ * This value SHALL be reset at the beginning of every staking period. */ int64 unclaimed_stake_reward_start = 7; + /** - * The total amount of effective hbar staked to this node. This is sum of stake_to_reward and stake_to_not_reward. - * If the sum is greater than max_stake, then the effective stake is max_stake. - * If the sum is less than min_stake, then the effective stake is 0. + * The total amount of HBAR staked to this node. + *

+ * This is sum of stake_to_reward and stake_to_not_reward.
+ * If the sum is greater than `max_stake`, then the _effective_ stake + * SHALL be `max_stake`.
+ * If the sum is less than `min_stake`, then the _effective_ stake + * SHALL be `0`. */ int64 stake = 8; + /** - * An running sum of reward rates per hbar for the last 365+1 staking periods. The first element is the - * is the reward up to and including the last full period that finished before the present. Second element is - * the reward up to and including the period before that + * A running list of reward amounts for the last 365+1 staking periods + * (typically a year and a day). + *

+ * The first element SHALL be the reward up to and including the last full + * period prior to the present reward period.
+ * The second element SHALL be the reward up to and including the period + * before the last full period prior to the present period.
+ * The list SHALL continue in reverse chronological order until the reward + * history limit is reached. */ repeated int64 reward_sum_history = 9; + /** - * The consensus weight of this node in the network. This is computed based on the stake of this node - * at midnight UTC of the current day. If the stake of this node is less than minStake, then the weight is 0. - * Sum of all weights of nodes in the network should be less than 500. - * If the stake of this node A is greater than minStake, then the weight of this node A is calculated as: - * (node A stake * 500/ total stake of all nodes) + * The consensus weight of this node in the network. + *

+ * This is recomputed based on the `stake` of this node at midnight UTC of + * each day. If the `stake` of this node at that time is less than + * `min_stake`, then the weight SHALL be 0.
+ *

+ * Given the following: + *

    + *
  • The `effective stake` of a single node SHALL be `0` if the node + * `stake` is less than `min_stake`.
    • + *
  • The `effective stake` SHALL be `max_stake` if the node `stake` is + * greater than `max_stake`.
    • + *
  • The `effective stake` SHALL be the actual value of `stake` if + * `min_stake` < `stake` < `max_stake`.
    • + *
  • The `effective network stake` SHALL be calculated as ∑(`effective + * stake` of each node) for all nodes in the network address book.
    • + *
+ *

+ * This field is deprecated and SHALL NOT be used when RosterLifecycle + * is enabled. The weight SHALL be same as the `effective_stake` described above. */ - int32 weight = 10; + int32 weight = 10 [deprecated = true]; + /** - * The total staking rewards in tinybars that COULD be collected by all accounts staking to the current node after the end - * of this staking period; assuming that no account "renounces" its rewards by, for example, setting declineReward=true. - * When the current node is deleted, this amount will be subtracted from the total pending rewards of all accounts staking - * to all nodes in the network in NetworkStakingRewards. + * The total staking rewards in tinybars that MAY be collected by all + * accounts staking to the current node after the end of this staking + * period. + *

+ * This SHALL be calculated assuming that no account "renounces" its + * rewards by setting `decline_reward` to true, or is ineligible for + * some other reason.
+ * When the current node is deleted, this amount SHALL be subtracted from + * the total pending rewards of all accounts staking to all nodes in the + * network in NetworkStakingRewards. */ int64 pending_rewards = 11; + /** - * True if this node has been deleted from network. + * A flag indicating that this node has been removed from this network. */ bool deleted = 12; } diff --git a/sdk/src/main/proto/state_signature_transaction.proto b/sdk/src/main/proto/state_signature_transaction.proto new file mode 100644 index 000000000..a8d55010b --- /dev/null +++ b/sdk/src/main/proto/state_signature_transaction.proto @@ -0,0 +1,64 @@ +/** + * # State Signature Transaction + * An signature of a state snapshot gossiped to other nodes. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119). + */ +syntax = "proto3"; + +package com.hedera.hapi.platform.event; + +/* + * Hedera Network Services Protobuf + * + * Copyright (C) 2018 - 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +option java_package = "com.hedera.hapi.platform.event.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * An signature of a state snapshot gossiped to other nodes. + * Each node SHALL hash the root of the merkle tree of a state snapshot every + * round. Once this hash is calculated, it SHOULD be signed with the nodes + * private signing key. This signature, together with the hash SHOULD be added + * to an event as a StateSignatureTransaction. + */ +message StateSignatureTransaction { + + /** + * The round number corresponding to the round number of the state snapshot + * being signed.
+ * This number MUST be greater than 0. + */ + int64 round = 1; + + /** + * The signature of state snapshot hash.
+ * This signature MUST be a RSA signature with a maximum length of 384 bytes.
+ * The signature algorithm used MUST be RSASSA-PKCS1-v1_5 with SHA-384. + */ + bytes signature = 2; + + /** + * The hash of the state snapshot being signed.
+ * This hash MUST be a SHA-384 hash. + */ + bytes hash = 3; +} diff --git a/sdk/src/main/proto/storage_slot.proto b/sdk/src/main/proto/storage_slot.proto index 59d3e8dd5..0de010f97 100644 --- a/sdk/src/main/proto/storage_slot.proto +++ b/sdk/src/main/proto/storage_slot.proto @@ -1,13 +1,21 @@ +/** + * # EVM Contract Slot + * Information regarding EVM storage "slot"s for the + * Hedera Smart Contract service. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,32 +36,33 @@ option java_multiple_files = true; import "basic_types.proto"; /** - * The key of a storage slot. A slot is scoped to a specific contract number. + * The key of a storage slot. A slot is scoped to a specific contract ID. * - * For each contract, its EVM storage is a mapping of 256-bit keys (or "words") to 256-bit values. + * For each contract, its EVM storage is a mapping of 256-bit keys (or "words") + * to 256-bit values. */ message SlotKey { /** - * The number of the contract whose storage this slot belongs to. + * The Contract ID of the contract that owns (and pays for) this slot. */ ContractID contractID = 1; /** - * The EVM key of this slot, when left-padded with zeros to form a 256-bit word. + * The EVM key of this slot, left-padded with zeros to form a 256-bit word. */ bytes key = 2; } /** - * The value of a contract storage slot. For the EVM, this is a single word. + * The value of a contract storage slot. For the EVM, this is a single "word". * * Because we iterate through all the storage slots for an expired contract - * when purging it from state, our slot values also include the words - * of the previous and next keys in this contract's storage "list". + * when purging it from state, our slot values also include the words of the + * previous and next keys in this contract's storage "virtual linked list". */ message SlotValue { /** - * The EVM value in this slot, when left-padded with zeros to form a 256-bit word. + * The EVM value in this slot, left-padded with zeros to form a 256-bit word. */ bytes value = 1; diff --git a/sdk/src/main/proto/system_delete.proto b/sdk/src/main/proto/system_delete.proto index 9c228b411..00af7e366 100644 --- a/sdk/src/main/proto/system_delete.proto +++ b/sdk/src/main/proto/system_delete.proto @@ -1,13 +1,32 @@ +/** + * # System Delete + * A system transaction to remove a file from the Hedera File + * Service (HFS).
+ * This transaction is a privileged operation restricted to "system" + * accounts. + * + * > Note + * >> System delete is defined here for a smart contract (to delete + * >> the bytecode), but was never implemented. + * > + * >> Currently, system delete and system undelete specifying a smart + * >> contract identifier SHALL return `INVALID_FILE_ID` + * >> or `MISSING_ENTITY_ID`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +38,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -30,28 +48,57 @@ 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 contract bytecode as an administrative transaction. + * + * > Note + * >> A system delete/undelete for a `contractID` is not supported and + * >> SHALL return `INVALID_FILE_ID` or `MISSING_ENTITY_ID`. + * + * This transaction MAY be reversed by the `systemUndelete` transaction. + * A file deleted via `fileDelete`, however SHALL be irrecoverable.
+ * This transaction MUST specify an expiration timestamp (with seconds + * precision). The file SHALL be permanently removed from state when + * network consensus time exceeds the specified expiration time.
+ * This transaction MUST be signed by an Hedera administrative ("system") + * account. + * + * ### What is a "system" file + * A "system" file is any file with a file number less than or equal to the + * current configuration value for `ledger.numReservedSystemEntities`, + * typically `750`. + * + * ### Block Stream Effects + * None */ message SystemDeleteTransactionBody { oneof id { /** - * The file ID of the file to delete, in the format used in transactions + * A file identifier. + *

+ * The identified file MUST exist in the HFS.
+ * The identified file MUST NOT be deleted.
+ * The identified file MUST NOT be a "system" file.
+ * This field is REQUIRED. */ FileID fileID = 1; /** - * The contract ID instance to delete, in the format used in transactions + * A contract identifier. + *

+ * The identified contract MUST exist in network state.
+ * The identified contract bytecode MUST NOT be deleted.
+ *

+ * This option is _unsupported_. */ ContractID contractID = 2; } /** - * The timestamp in seconds at which the "deleted" file should truly be permanently deleted + * A timestamp indicating when the file will be removed from state. + *

+ * This value SHALL be expressed in seconds since the `epoch`. The `epoch` + * SHALL be the UNIX epoch with 0 at `1970-01-01T00:00:00.000Z`.
+ * This field is REQUIRED. */ TimestampSeconds expirationTime = 3; } diff --git a/sdk/src/main/proto/system_undelete.proto b/sdk/src/main/proto/system_undelete.proto index 68e92e9ec..5e8edbd0a 100644 --- a/sdk/src/main/proto/system_undelete.proto +++ b/sdk/src/main/proto/system_undelete.proto @@ -1,13 +1,31 @@ +/** + * # System Undelete + * A system transaction to "undo" a `systemDelete` transaction.
+ * This transaction is a privileged operation restricted to "system" + * accounts. + * + * > Note + * >> System undelete is defined here for a smart contract (to delete + * >> the bytecode), but was never implemented. + * > + * >> Currently, system delete and system undelete specifying a smart + * >> contract identifier SHALL return `INVALID_FILE_ID` + * >> or `MISSING_ENTITY_ID`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +37,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,18 +46,49 @@ 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. + * Recover a file or contract bytecode deleted from the Hedera File + * System (HFS) by a `systemDelete` transaction. + * + * > Note + * >> A system delete/undelete for a `contractID` is not supported and + * >> SHALL return `INVALID_FILE_ID` or `MISSING_ENTITY_ID`. + * + * This transaction can _only_ recover a file removed with the `systemDelete` + * transaction. A file deleted via `fileDelete` SHALL be irrecoverable.
+ * This transaction MUST be signed by an Hedera administrative ("system") + * account. + * + * ### What is a "system" file + * A "system" file is any file with a file number less than or equal to the + * current configuration value for `ledger.numReservedSystemEntities`, + * typically `750`. + * + * ### Block Stream Effects + * None */ message SystemUndeleteTransactionBody { oneof id { /** - * The file ID to undelete, in the format used in transactions + * A file identifier. + *

+ * The identified file MUST exist in the HFS.
+ * The identified file MUST be deleted.
+ * The identified file deletion MUST be a result of a + * `systemDelete` transaction.
+ * The identified file MUST NOT be a "system" file.
+ * This field is REQUIRED. */ FileID fileID = 1; /** - * The contract ID instance to undelete, in the format used in transactions + * A contract identifier. + *

+ * The identified contract MUST exist in network state.
+ * The identified contract bytecode MUST be deleted.
+ * The identified contract deletion MUST be a result of a + * `systemDelete` transaction. + *

+ * This option is _unsupported_. */ ContractID contractID = 2; } diff --git a/sdk/src/main/proto/throttle_definitions.proto b/sdk/src/main/proto/throttle_definitions.proto index 063a1223e..4139e98d5 100644 --- a/sdk/src/main/proto/throttle_definitions.proto +++ b/sdk/src/main/proto/throttle_definitions.proto @@ -1,13 +1,29 @@ +/** + * # Throttle Definitions + * A set of messages that support maintaining throttling limits on network + * transactions to ensure no one transaction type consumes the entirety of + * network resources. Also used to charge congestion fees when network load + * is exceptionally high, as an incentive to delay transactions that are + * not time-sensitive. + * + * For details behind this throttling design, please see the + * `docs/throttle-design.md` document in the + * [Hedera Services](https://github.com/hashgraph/hedera-services) repository. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +35,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,58 +44,106 @@ 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. - */ - -/** - * A set of operations which should be collectively throttled at a given milli-ops-per-second limit. + * A single throttle limit applied to one or more operations. + * + * The list of operations MUST contain at least one entry.
+ * The throttle limit SHALL be specified in thousandths of an operation + * per second; one operation per second for the network would be `1000`.
+ * The throttle limit MUST be greater than zero (`0`). */ message ThrottleGroup { /** - * The operations to be throttled + * A list of operations to be throttled. + *

+ * This list MUST contain at least one item.
+ * This list SHOULD NOT contain any item included in any other + * active `ThrottleGroup`. */ 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. + * A throttle limit for this group.
+ * This is a total number of operations, in thousandths, the network may + * perform each second for this group. Every node executes every transaction, + * so this limit effectively applies individually to each node as well.
+ *

+ * This value MUST be greater than zero (`0`).
+ * This value SHOULD be less than `9,223,372`.
*/ uint64 milliOpsPerSec = 2; } /** - * A list of throttle groups that should all compete for the same internal bucket. + * A "bucket" of performance allocated across one or more throttle groups.
+ * This entry combines one or more throttle groups into a single unit to + * calculate limitations and congestion. Each "bucket" "fills" as operations + * are completed, then "drains" over a period of time defined for each bucket. + * This fill-and-drain characteristic enables the network to process sudden + * bursts of heavy traffic while still observing throttle limits over longer + * timeframes. + * + * The value of `burstPeriodMs` is combined with the `milliOpsPerSec` + * values for the individual throttle groups to determine the total + * bucket "capacity". This combination MUST be less than the maximum + * value of a signed long integer (`9223372036854775807`), when scaled to + * a nanosecond measurement resolution. + * + * > Note + * >> There is some question regarding the mechanism of calculating the + * >> combination of `burstPeriodMs` and `milliOpsPerSec`. The calculation + * >> Is implemented in difficult-to-find code, and very likely does not + * >> match the approach described here. */ message ThrottleBucket { /** - * A name for this bucket (primarily for use in logs) + * A name for this bucket.
+ * This is used for log entries. + *

+ * This value SHOULD NOT exceed 20 characters. */ 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. + * A burst duration limit, in milliseconds.
+ * This value determines the total "capacity" of the bucket. The rate + * at which the bucket "drains" is set by the throttles, and this duration + * sets how long that rate must be sustained to empty a "full" bucket. + * That combination (calculated as the product of this value and the least + * common multiple of the `milliOpsPerSec` values for all throttle groups) + * determines the maximum amount of operations this bucket can "hold". + *

+ * The calculated capacity of this bucket MUST NOT exceed `9,223,372,036,854`. */ uint64 burstPeriodMs = 2; /** - * The throttle groups competing for this bucket + * A list of throttle groups.
+ * These throttle groups combined define the effective throttle + * rate for the bucket. + *

+ * This list MUST contain at least one entry. */ 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.
+ * This list, simultaneously enforced, defines a complete throttling policy. + * + * 1. When an operation appears in more than one throttling bucket, + * that operation SHALL be throttled unless all of the buckets where + * the operation appears have "capacity" available. + * 1. An operation assigned to no buckets is SHALL be throttled in every + * instance. The _effective_ throttle for this case is `0`. */ message ThrottleDefinitions { - repeated ThrottleBucket throttleBuckets = 1; + /** + * A list of throttle buckets. + *

+ * This list MUST be set, and SHOULD NOT be empty.
+ * An empty list SHALL have the effect of setting all operations to + * a single group with throttle limit of `0` operations per second for the + * entire network. + */ + repeated ThrottleBucket throttleBuckets = 1; } diff --git a/sdk/src/main/proto/throttle_usage_snapshots.proto b/sdk/src/main/proto/throttle_usage_snapshots.proto index b325b6b26..5d40c522b 100644 --- a/sdk/src/main/proto/throttle_usage_snapshots.proto +++ b/sdk/src/main/proto/throttle_usage_snapshots.proto @@ -1,13 +1,20 @@ +/** + * # Throttle Snapshots + * Point-in-time information regarding throttle usage. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +26,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ import "timestamp.proto"; @@ -28,25 +34,46 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; +/** + * All point-in-time snapshots of throttle usage for TPS and "gas" throttle + * values for a given point in time. + * + * > Question: + * >> What point in time? Should this store consensus timestamp here? + */ message ThrottleUsageSnapshots { - /** - * Snapshots for TPS throttles. - */ - repeated ThrottleUsageSnapshot tps_throttles = 1; - - /** - * Snapshots for gas throttle. - */ - ThrottleUsageSnapshot gas_throttle = 2; + + /** + * A list of snapshots for TPS throttles. + *

+ *

Question:
What is the order?
+ */ + repeated ThrottleUsageSnapshot tps_throttles = 1; + + /** + * A single snapshot for the gas throttle. + */ + ThrottleUsageSnapshot gas_throttle = 2; } +/** + * A single snapshot of the used throttle capacity for a throttle and point in + * time. + * + * > Question: + * >> What throttle does this apply to? How is that determined? + */ message ThrottleUsageSnapshot { - /** - * Used throttle capacity. - */ - int64 used = 1; - /** - * The last time at which the capacity was updated. - */ - Timestamp last_decision_time = 2; + /** + * Used throttle capacity. + */ + int64 used = 1; + + /** + * The time at which the this snapshot of capacity was calculated.
+ * Stored as an offset from the `epoch`. + *

+ * For this purpose, `epoch` SHALL be the UNIX epoch with 0 at `1970-01-01T00:00:00.000Z`. + */ + Timestamp last_decision_time = 2; } diff --git a/sdk/src/main/proto/timestamp.proto b/sdk/src/main/proto/timestamp.proto index 0ca2798a7..85fa25b46 100644 --- a/sdk/src/main/proto/timestamp.proto +++ b/sdk/src/main/proto/timestamp.proto @@ -1,13 +1,22 @@ +/** + * # Timestamp + * Messages to describe exact date-time values, with resolution of seconds or + * nanoseconds, referenced to the UNIX epoch. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,28 +35,45 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; 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 Google protobuf Timestamp.proto. + * + * #### Additional Notes + * Useful information is present in comments on the + * [Google version](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). */ message Timestamp { /** - * Number of complete seconds since the start of the epoch + * The number of complete seconds since the start of the epoch. + *

+ * For this purpose, `epoch` SHALL be the UNIX epoch with 0 + * at `1970-01-01T00:00:00.000Z`.
+ * This value MUST be greater than 0.
+ * This value SHOULD be strictly greater than `946684800`. */ int64 seconds = 1; /** - * Number of nanoseconds since the start of the last second + * The number of nanoseconds after the start of the second referenced + * in `seconds`. + *

+ * This value MUST be greater than or equal to 0.
+ * This value MUST be strictly less than 1,000,000,000. */ 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. */ message TimestampSeconds { /** - * Number of complete seconds since the start of the epoch + * The number of complete seconds since the start of the epoch. + *

+ * For this purpose, `epoch` SHALL be the UNIX epoch with 0 + * at `1970-01-01T00:00:00.000Z`.
+ * This value MUST be greater than 0.
+ * This value SHOULD be strictly greater than `946684800`. */ int64 seconds = 1; } - diff --git a/sdk/src/main/proto/token.proto b/sdk/src/main/proto/token.proto index 78a6c60a9..71e0c5c21 100644 --- a/sdk/src/main/proto/token.proto +++ b/sdk/src/main/proto/token.proto @@ -1,13 +1,21 @@ +/** + * ## Token + * Tokens represent both fungible and non-fungible units of exchange. + * The `Token` here represents a token within the network state. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ import "basic_types.proto"; @@ -30,146 +37,329 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** - * Representation of a Hedera Token Service token entity in the network Merkle tree. + * An Hedera Token Service(HTS) token. + * + * A token SHALL represent a fungible or non-fungible unit of exchange.
+ * The specified Treasury Account SHALL receive the initial supply of tokens and + * SHALL determine distribution of all tokens once minted. * - * As with all network entities, a token has a unique entity number, which is usually given along - * with the network's shard and realm in the form of a shard.realm.number id. */ - message Token { /** - * The unique entity id of this token. + * A unique identifier for this token. */ TokenID token_id = 1; + /** - * The human-readable name of this token. Need not be unique. Maximum length allowed is 100 bytes. + * A human-readable name for this token. + *

+ * This value MAY NOT be unique.
+ * This value SHALL NOT exceed 100 bytes when encoded as UTF-8. */ string name = 2; + /** - * The human-readable symbol for the token. It is not necessarily unique. Maximum length allowed is 100 bytes. + * A human-readable symbol for the token. + *

+ * This value SHALL NOT be unique.
+ * This value SHALL NOT exceed 100 bytes when encoded as UTF-8. */ string symbol = 3; + /** - * The number of decimal places of this token. If decimals are 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). + * A number of decimal places for this token. + *

+ * If decimals are 8 or 11, then the number of whole tokens can be at most + * billions or millions, respectively. More decimals allows for a more + * finely-divided token, but also limits the maximum total supply. + *

+ * Examples + *

    + *
  • Bitcoin satoshis (21 million whole tokens with 8 decimals).
    • + *
  • Hedera tinybar (50 billion whole tokens with 8 decimals).
    • + *
  • Bitcoin milli-satoshis (21 million whole tokens with 11 decimals).
    • + *
  • Theoretical limit is roughly 92.2 billion with 8 decimals, or + * 92.2 million with 11 decimals.
    • + *
+ * All token amounts in the network are stored as integer amounts, with each + * unit representing 10-decimals whole tokens. + *

+ * For tokens with `token_type` set to `NON_FUNGIBLE_UNIQUE` this MUST be 0. */ int32 decimals = 4; + /** - * The total supply of this token. + * A _current_ total supply of this token, expressed in the smallest unit + * of the token. + *

+ * The number of _whole_ tokens this represents is (total_supply / + * 10decimals). The value of total supply, MUST be within the + * positive range of a twos-compliment signed 64-bit integer. + * The `total_supply`, therefore MUST be between 1, and + * 9,223,372,036,854,775,807, inclusive. + *

+ * This value SHALL be reduced when a `token_burn` or `token_wipe_account` + * operation is executed, and SHALL be increased when a `token_mint` + * operation is executed. */ int64 total_supply = 5; + /** - * The treasury account id of this token. This account receives 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. + * A treasury account identifier for this token. + *

+ * When the token is created, the initial supply given in the token create + * transaction SHALL be minted and deposited in the treasury account.
+ * All token mint transactions for this token SHALL deposit the new minted + * tokens in the treasury account.
+ * All token burn transactions for this token SHALL remove the tokens to be + * burned from the treasury account. */ AccountID treasury_account_id = 6; + /** - * (Optional) The admin key of this token. If this key is set, the token is mutable. - * A mutable token can be modified. - * If this key is not set on token creation, it cannot be modified. + * Access control for general modification of this token. + *

+ * This key MUST sign any `token_update` transaction that + * changes any attribute of the token other than expiration_time. + * Other attributes of this token MAY be changed by transactions other than + * `token_update`, and MUST be signed by one of the other purpose-specific + * keys assigned to the token.
+ * This value can be set during token creation, and SHALL NOT be + * modified thereafter, unless the update transaction is signed by both + * the existing `admin_key` and the new `admin_key`.
+ * If the `admin_key` is not set for a token, that token SHALL be immutable. */ Key admin_key = 7; + /** - * (Optional) The kyc key of this token. - * If this key is not set on token creation, it can only be set if the token has admin key set. + * Access control for KYC for this token. + *

+ * Know Your Customer (KYC) status may be granted for an account by a token + * grant kyc transaction signed by this key.
+ * If this key is not set, then KYC status cannot be granted to an account + * for this token, and any `TokenGrantKyc` transaction attempting to grant + * kyc to an account for this token SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key kyc_key = 8; + /** - * (Optional) The freeze key of this token. This key is needed for freezing the token. - * If this key is not set on token creation, it can only be set if the token has admin key set. + * Access control to freeze this token. + *

+ * A token may be frozen for an account, preventing any transaction from + * transferring that token for that specified account, by a token freeze + * account transaction signed by this key.
+ * If this key is not set, the token cannot be frozen, and any transaction + * attempting to freeze the token for an account SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key freeze_key = 9; + /** - * (Optional) The wipe key of this token. This key is needed for wiping the token. - * If this key is not set on token creation, it can only be set if the token has admin key set. + * Access control of account wipe for this token. + *

+ * A token may be wiped, removing and burning tokens from a specific + * account, by a token wipe transaction, which MUST be signed by this key. + * The `treasury_account` cannot be subjected to a token wipe. A token burn + * transaction, signed by the `supply_key`, serves to burn tokens held by + * the `treasury_account` instead.
+ * If this key is not set, the token cannot be wiped, and any transaction + * attempting to wipe the token from an account SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key wipe_key = 10; + /** - * (Optional) The supply key of this token. This key is needed for minting or burning token. - * If this key is not set on token creation, it can only be set if the token has admin key set. + * Access control of token mint/burn for this token. + *

+ * A token mint transaction MUST be signed by this key, and any token mint + * transaction not signed by the current `supply_key` for that token + * SHALL NOT succeed.
+ * A token burn transaction MUST be signed by this key, and any token burn + * transaction not signed by the current `supply_key` for that token + * SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key supply_key = 11; + /** - * (Optional) The fee schedule key of this token. This key should be set, in order to make any - * changes to the custom fee schedule. - * If this key is not set on token creation, it can only be set if the token has admin key set. + * Access control of the `custom_fees` field for this token. + *

+ * The token custom fee schedule may be changed, modifying the fees charged + * for transferring that token, by a token update transaction, which MUST + * be signed by this key.
+ * If this key is not set, the token custom fee schedule cannot be changed, + * and any transaction attempting to change the custom fee schedule for + * this token SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key fee_schedule_key = 12; + /** - * (Optional) The pause key of this token. This key is needed for pausing the token. - * If this key is not set on token creation, it can only be set if the token has admin key set. + * Access control of pause/unpause for this token. + *

+ * A token may be paused, preventing any transaction from transferring that + * token, by a token update transaction signed by this key.
+ * If this key is not set, the token cannot be paused, and any transaction + * attempting to pause the token SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key pause_key = 13; + /** - * The last used serial number of this token. + * A last used serial number for this token. + *

+ * This SHALL apply only to non-fungible tokens.
+ * When a new NFT is minted, the serial number to apply SHALL be calculated + * from this value. */ int64 last_used_serial_number = 14; + /** - * The flag indicating if this token is deleted. + * A flag indicating that this token is deleted. + *

+ * A transaction involving a deleted token MUST NOT succeed. */ bool deleted = 15; + /** - * The type of this token. A token can be either FUNGIBLE_COMMON or NON_FUNGIBLE_UNIQUE. - * If it has been omitted during token creation, FUNGIBLE_COMMON type is used. + * A type for this token. + *

+ * A token SHALL be either `FUNGIBLE_COMMON` or `NON_FUNGIBLE_UNIQUE`.
+ * If this value was omitted during token creation, `FUNGIBLE_COMMON` + * SHALL be used. */ TokenType token_type = 16; + /** - * The supply type of this token.A token can have either INFINITE or FINITE supply type. - * If it has been omitted during token creation, INFINITE type is used. + * A supply type for this token. + *

+ * A token SHALL have either `INFINITE` or `FINITE` supply type.
+ * If this value was omitted during token creation, the value `INFINITE` + * SHALL be used. */ TokenSupplyType supply_type = 17; + /** - * The id of the account (if any) that the network will attempt to charge for the - * token's auto-renewal upon expiration. + * An identifier for the account (if any) that the network will attempt + * to charge for this token's auto-renewal upon expiration. + *

+ * This field is OPTIONAL. If it is not set then renewal fees SHALL be + * charged to the account identified by `treasury_account_id`. */ AccountID auto_renew_account_id = 18; + /** - * The number of seconds the network should automatically extend the token's expiration by, if the - * token has a valid auto-renew account, and is not deleted upon expiration. - * If this is not provided in a allowed range on token creation, the transaction will fail with INVALID_AUTO_RENEWAL_PERIOD. - * The default values for the minimum period and maximum period are 30 days and 90 days, respectively. + * A number of seconds by which the network should automatically extend + * this token's expiration. + *

+ * If the token has a valid auto-renew account, and is not deleted upon + * expiration, the network SHALL attempt to automatically renew this + * token.
+ * If this is not provided in an allowed range on token creation, the + * transaction SHALL fail with `INVALID_AUTO_RENEWAL_PERIOD`.
+ * The default values for the minimum period and maximum period are 30 days + * and 90 days, respectively. */ int64 auto_renew_seconds = 19; + /** - * The expiration time of the token, in seconds since the epoch. + * An expiration time for this token, in seconds since the epoch. + *

+ * For this purpose, `epoch` SHALL be the + * UNIX epoch with 0 at `1970-01-01T00:00:00.000Z`. */ int64 expiration_second = 20; + /** - * An optional description of the token with UTF-8 encoding up to 100 bytes. + * A short description of this token. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 21; + /** - * The maximum supply of this token. + * A maximum supply of this token.
+ * This is the maximum number of tokens of this type that may be issued. + *

+ * This limit SHALL apply regardless of `token_type`.
+ * If `supply_type` is `INFINITE` then this value MUST be 0.
+ * If `supply_type` is `FINITE`, then this value MUST be greater than 0. */ int64 max_supply = 22; + /** - * The flag indicating if this token is paused. + * A flag indicating that this token is paused. + *

+ * A transaction involving a paused token, other than token_unpause, + * MUST NOT succeed. */ bool paused = 23; + /** - * The flag indicating if this token has accounts associated to it that are frozen by default. + * A flag indicating that accounts associated to this token are frozen by + * default. + *

+ * Accounts newly associated with this token CANNOT transact in the token + * until unfrozen.
+ * This SHALL NOT prevent a `tokenReject` transaction to return the tokens + * from an account to the treasury account. */ bool accounts_frozen_by_default = 24; + /** - * The flag indicating if this token has accounts associated with it that are KYC granted by default. - */ + * A flag indicating that accounts associated with this token are granted + * KYC by default. + */ bool accounts_kyc_granted_by_default = 25; + /** - * (Optional) The custom fees of this token. + * A custom fee schedule for this token. */ repeated CustomFee custom_fees = 26; /** - * Metadata of the created token definition + * A Token "Metadata". + *

+ * This value, if set, SHALL NOT exceed 100 bytes. */ bytes metadata = 27; /** - * The key which can change the metadata of a token - * (token definition and individual NFTs). + * Access Control of metadata update for this token. + *

+ * A transaction to update the `metadata` field of this token MUST be + * signed by this key.
+ * If this token is a non-fungible/unique token type, a transaction to + * update the `metadata` field of any individual serialized unique token + * of this type MUST be signed by this key.
+ * If this key is not set, the token metadata SHALL NOT be changed after it + * is created.
+ * If this key is not set, the metadata for any individual serialized token + * of this type SHALL NOT be changed after it is created.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key metadata_key = 28; } diff --git a/sdk/src/main/proto/token_airdrop.proto b/sdk/src/main/proto/token_airdrop.proto index cef39a285..cede6fdbf 100644 --- a/sdk/src/main/proto/token_airdrop.proto +++ b/sdk/src/main/proto/token_airdrop.proto @@ -8,7 +8,9 @@ * ### Keywords * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119). + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). */ syntax = "proto3"; @@ -40,61 +42,76 @@ import "basic_types.proto"; * Airdrop one or more tokens to one or more accounts. * * ### Effects - * This distributes tokens from the balance of one or more sending account(s) to the balance - * of one or more recipient accounts. Accounts MAY receive the tokens in one of four ways. + * This distributes tokens from the balance of one or more sending account(s) + * to the balance of one or more recipient accounts. Accounts MAY receive the + * tokens in one of four ways. * - * - An account already associated to the token to be distributed SHALL receive the - * airdropped tokens immediately to the recipient account balance.
- * The fee for this transfer SHALL include the transfer, the airdrop fee, and any custom fees. - * - An account with available automatic association slots SHALL be automatically - * associated to the token, and SHALL immediately receive the airdropped tokens to the - * recipient account balance.
- * The fee for this transfer SHALL include the transfer, the association, the cost to renew - * that association once, the airdrop fee, and any custom fees. - * - An account with "receiver signature required" set SHALL have a "Pending Airdrop" created - * and must claim that airdrop with a `claimAirdrop` transaction.
- * The fee for this transfer SHALL include the transfer, the association, the cost to renew - * that association once, the airdrop fee, and any custom fees. If the pending airdrop is not - * claimed immediately, the `sender` SHALL pay the cost to renew the token association, and - * the cost to maintain the pending airdrop, until the pending airdrop is claimed or cancelled. - * - An account with no available automatic association slots SHALL have a "Pending Airdrop" - * created and must claim that airdrop with a `claimAirdrop` transaction.
- * The fee for this transfer SHALL include the transfer, the association, the cost to renew - * that association once, the airdrop fee, and any custom fees. If the pending airdrop is not - * claimed immediately, the `sender` SHALL pay the cost to renew the token association, and - * the cost to maintain the pending airdrop, until the pending airdrop is claimed or cancelled. + * - An account already associated to the token to be distributed SHALL + * receive the airdropped tokens immediately to the recipient account + * balance.
+ * The fee for this transfer SHALL include the transfer, the airdrop fee, + * and any custom fees. + * - An account with available automatic association slots SHALL be + * automatically associated to the token, and SHALL immediately receive + * the airdropped tokens to the recipient account balance.
+ * The fee for this transfer SHALL include the transfer, the association, + * the cost to renew that association once, the airdrop fee, and + * any custom fees. + * - An account with "receiver signature required" set SHALL have a + * "Pending Airdrop" created and must claim that airdrop with a + * `claimAirdrop` transaction.
+ * The fee for this transfer SHALL include the transfer, the association, + * the cost to renew that association once, the airdrop fee, and + * any custom fees.
+ * If the pending airdrop is not claimed immediately, the `sender` SHALL + * pay the cost to renew the token association, and the cost to maintain + * the pending airdrop, until the pending airdrop is claimed or cancelled. + * - An account with no available automatic association slots SHALL have a + * "Pending Airdrop" created and must claim that airdrop with a + * `claimAirdrop` transaction.
+ * The fee for this transfer SHALL include the transfer, the association, + * the cost to renew that association once, the airdrop fee, and any custom + * fees.
+ * If the pending airdrop is not claimed immediately, the `sender` SHALL + * pay the cost to renew the token association, and the cost to maintain + * the pending airdrop, until the pending airdrop is claimed or cancelled. * - * If an airdrop would create a pending airdrop for a fungible/common token, and a pending airdrop - * for the same sender, receiver, and token already exists, the existing pending airdrop - * SHALL be updated to add the new amount to the existing airdrop, rather than creating a new - * pending airdrop. + * If an airdrop would create a pending airdrop for a fungible/common token, + * and a pending airdrop for the same sender, receiver, and token already + * exists, the existing pending airdrop SHALL be updated to add the new + * amount to the existing airdrop, rather than creating + * a new pending airdrop.
+ * Any airdrop that completes immediately SHALL be irreversible. Any airdrop + * that results in a "Pending Airdrop" MAY be canceled via a `cancelAirdrop` + * transaction.
+ * All transfer fees (including custom fees and royalties), as well as the + * rent cost for the first auto-renewal period for any automatic-association + * slot occupied by the airdropped tokens, SHALL be charged to the account + * paying for this transaction.
* - * Any airdrop that completes immediately SHALL be irreversible. Any airdrop that results in a - * "Pending Airdrop" MAY be canceled via a `cancelAirdrop` transaction. - * - * All transfer fees (including custom fees and royalties), as well as the rent cost for the - * first auto-renewal period for any automatic-association slot occupied by the airdropped - * tokens, SHALL be charged to the account paying for this transaction. - * - * ### Record Stream Effects - * - Each successful transfer SHALL be recorded in `token_transfer_list` for the transaction record. - * - Each successful transfer that consumes an automatic association slot SHALL populate the - * `automatic_association` field for the record. - * - Each pending transfer _created_ SHALL be added to the `pending_airdrops` field for the record. - * - Each pending transfer _updated_ SHALL be added to the `pending_airdrops` field for the record. + * ### Block Stream Effects + * - Each successful transfer SHALL be recorded in `token_transfer_list` + * for the transaction record. + * - Each successful transfer that consumes an automatic association slot + * SHALL populate the `automatic_association` field for the record. + * - Each pending transfer _created_ SHALL be added to the + * `pending_airdrops` field for the record. + * - Each pending transfer _updated_ SHALL be added to the + * `pending_airdrops` field for the record. */ message TokenAirdropTransactionBody { - /** - * A list of token transfers representing one or more airdrops. - * The sender for each transfer MUST have sufficient balance to complete the transfers. - * - * All token transfers MUST successfully transfer tokens or create a pending airdrop - * for this transaction to succeed. - * This list MUST contain between 1 and 10 transfers, inclusive. - * - * Note that each transfer of fungible/common tokens requires both a debit and - * a credit, so each _fungible_ token transfer MUST have _balanced_ entries in the - * TokenTransferList for that transfer. - */ - repeated TokenTransferList token_transfers = 1; + /** + * A list of token transfers representing one or more airdrops. + *

+ * The sender for each transfer MUST have sufficient balance to complete + * the transfers.
+ * All token transfers MUST successfully transfer tokens or create a + * pending airdrop for this transaction to succeed.
+ * This list MUST contain between 1 and 10 transfers, inclusive. + *

+ * Note that each transfer of fungible/common tokens requires both a debit + * and a credit, so each _fungible_ token transfer MUST have _balanced_ + * entries in the TokenTransferList for that transfer. + */ + repeated TokenTransferList token_transfers = 1; } diff --git a/sdk/src/main/proto/token_associate.proto b/sdk/src/main/proto/token_associate.proto index b1438b01a..d981ed9c3 100644 --- a/sdk/src/main/proto/token_associate.proto +++ b/sdk/src/main/proto/token_associate.proto @@ -1,13 +1,31 @@ +/** + * # Token Associate + * Transaction to associate an Hedera Token Service (HTS) token with an + * account.
+ * Accounts cannot transact in a token (send or receive) until the account + * and token are associated. + * + * > Note + * >> An "airdrop" transaction MAY initiate sending tokens to an + * >> unassociated account, but the transfer remains in a "pending" + * >> state until the recipient executes a "claim" transaction + * >> that both accepts the tokens and associates that account + * >> with the token type. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +37,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,29 +46,49 @@ 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. + * Associate an Hedera Token Service (HTS) token and an account. + * + * An association MUST exist between an account and a token before that + * account may transfer or receive that token.
+ * If the identified account is not found, + * the transaction SHALL return `INVALID_ACCOUNT_ID`.
+ * If the identified account has been deleted, + * the transaction SHALL return `ACCOUNT_DELETED`.
+ * If any of the identified tokens is not found, + * the transaction SHALL return `INVALID_TOKEN_REF`.
+ * If any of the identified tokens has been deleted, + * the transaction SHALL return `TOKEN_WAS_DELETED`.
+ * If an association already exists for any of the identified tokens, + * the transaction SHALL return `TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT`.
+ * The identified account MUST sign this transaction. + * + * ### Block Stream Effects + * None */ message TokenAssociateTransactionBody { /** - * The account to be associated with the provided tokens + * An account identifier. + *

+ * The identified account SHALL be associated to each of the + * tokens identified in the `tokens` field.
+ * This field is REQUIRED and MUST be a valid account identifier.
+ * The identified account MUST exist in state.
+ * The identified account MUST NOT be deleted.
+ * The identified account MUST NOT be expired. */ 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 + * A list of token identifiers. + *

+ * Each token identified in this list SHALL be separately associated with + * the account identified in the `account` field.
+ * This list MUST NOT be empty. + * Each entry in this list MUST be a valid token identifier.
+ * Each entry in this list MUST NOT be currently associated to the + * account identified in `account`.
+ * Each entry in this list MUST NOT be expired.
+ * Each entry in this list MUST NOT be deleted. */ repeated TokenID tokens = 2; } diff --git a/sdk/src/main/proto/token_burn.proto b/sdk/src/main/proto/token_burn.proto index d1763ea39..7fcb84a4a 100644 --- a/sdk/src/main/proto/token_burn.proto +++ b/sdk/src/main/proto/token_burn.proto @@ -1,13 +1,22 @@ +/** + * # Token Burn + * Permanently remove tokens from circulation, akin to how a fiat treasury + * will physically burn worn out bank notes. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,40 +37,58 @@ 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. + * Burns tokens from the Token's treasury Account. + * + * The token MUST have a `supply_key` set and that key MUST NOT + * be an empty `KeyList`.
+ * The token `supply_key` MUST sign this transaction.
+ * This operation SHALL decrease the total supply for the token type by + * the number of tokens "burned".
+ * The total supply for the token type MUST NOT be reduced below zero (`0`) + * by this transaction.
+ * The tokens to burn SHALL be deducted from the token treasury account.
+ * If the token is a fungible/common type, the amount MUST be specified.
+ * If the token is a non-fungible/unique type, the specific serial numbers + * MUST be specified.
+ * The global batch size limit (`tokens.nfts.maxBatchSizeBurn`) SHALL set + * the maximum number of individual NFT serial numbers permitted in a single + * `tokenBurn` transaction. * - * If the serialNumbers don't get filled for non-fungible token type, a INVALID_TOKEN_BURN_AMOUNT response - * code will be returned. - * If a zero amount is provided for a fungible token type, it will be treated as a regular transaction. - * 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. + * ### Block Stream Effects + * None */ message TokenBurnTransactionBody { /** - * The token for which to burn tokens. If token does not exist, transaction results in - * INVALID_TOKEN_ID + * A token identifier. + *

+ * This SHALL identify the token type to "burn".
+ * The identified token MUST exist, and MUST NOT be deleted. */ 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. + * An amount to burn from the Treasury Account. + *

+ * This is interpreted as an amount in the smallest possible denomination + * for the token (10-decimals whole tokens).
+ * The balance for the token treasury account MUST contain sufficient + * tokens to complete this transaction with a non-negative balance.
+ * If this value is equal to zero (`0`), the token SHOULD be a + * non-fungible/unique type.
+ * If this value is non-zero, the token MUST be a fungible/common type. */ uint64 amount = 2; /** - * Applicable to tokens of type NON_FUNGIBLE_UNIQUE. The list of serial numbers to be burned. + * A list of serial numbers to burn from the Treasury Account. + *

+ * This list MUST NOT contain more entries than the current limit set by + * the network configuration value `tokens.nfts.maxBatchSizeBurn`.
+ * The treasury account for the token MUST hold each unique token + * identified in this list.
+ * If this list is not empty, the token MUST be a + * non-fungible/unique type.
+ * If this list is empty, the token MUST be a fungible/common type. */ repeated int64 serialNumbers = 3; } diff --git a/sdk/src/main/proto/token_cancel_airdrop.proto b/sdk/src/main/proto/token_cancel_airdrop.proto index 074aee7ee..cdb09aa34 100644 --- a/sdk/src/main/proto/token_cancel_airdrop.proto +++ b/sdk/src/main/proto/token_cancel_airdrop.proto @@ -5,7 +5,9 @@ * ### Keywords * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119). + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). */ syntax = "proto3"; @@ -25,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -36,25 +37,29 @@ import "basic_types.proto"; /** * Token cancel airdrop
- * Remove one or more pending airdrops from state on behalf of the sender(s) - * for each airdrop. + * Remove one or more pending airdrops from state on behalf of the + * sender(s) for each airdrop. * - * Each pending airdrop canceled SHALL be removed from state and SHALL NOT be available to claim.
- * Each cancellation SHALL be represented in the transaction body and SHALL NOT be restated - * in the record file.
+ * Each pending airdrop canceled SHALL be removed from state and + * SHALL NOT be available to claim.
+ * Each cancellation SHALL be represented in the transaction body and + * SHALL NOT be restated in the record file.
* All cancellations MUST succeed for this transaction to succeed. + * + * ### Block Stream Effects + * None */ message TokenCancelAirdropTransactionBody { - /** - * A list of one or more pending airdrop identifiers.
- * This list declares the set of pending airdrop entries that the client - * wishes to cancel; on success all listed pending airdrop entries - * will be removed. - *

- * This transaction MUST be signed by the account referenced by a `sender_id` for - * each entry in this list.
- * This list MUST NOT have any duplicate entries.
- * This list MUST contain between 1 and 10 entries, inclusive. - */ - repeated PendingAirdropId pending_airdrops = 1; + /** + * A list of one or more pending airdrop identifiers.
+ * This list declares the set of pending airdrop entries that the client + * wishes to cancel; on success all listed pending airdrop entries + * will be removed. + *

+ * This transaction MUST be signed by the account identified by a + * `sender_id` for each entry in this list.
+ * This list MUST NOT have any duplicate entries.
+ * This list MUST contain between 1 and 10 entries, inclusive. + */ + repeated PendingAirdropId pending_airdrops = 1; } diff --git a/sdk/src/main/proto/token_claim_airdrop.proto b/sdk/src/main/proto/token_claim_airdrop.proto index 2d89789c4..c42bb6cf6 100644 --- a/sdk/src/main/proto/token_claim_airdrop.proto +++ b/sdk/src/main/proto/token_claim_airdrop.proto @@ -5,7 +5,9 @@ * ### Keywords * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119). + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). */ syntax = "proto3"; @@ -25,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -48,17 +49,17 @@ import "basic_types.proto"; * SHALL NOT be restated in the record file.
* All claims MUST succeed for this transaction to succeed. * - * ### Record Stream Effects + * ### Block Stream Effects * The completed transfers SHALL be present in the transfer list. */ message TokenClaimAirdropTransactionBody { - /** - * A list of one or more pending airdrop identifiers. - *

- * This transaction MUST be signed by the account identified by - * the `receiver_id` for each entry in this list.
- * This list MUST contain between 1 and 10 entries, inclusive.
- * This list MUST NOT have any duplicate entries. - */ - repeated PendingAirdropId pending_airdrops = 1; + /** + * A list of one or more pending airdrop identifiers. + *

+ * This transaction MUST be signed by the account identified by + * the `receiver_id` for each entry in this list.
+ * This list MUST contain between 1 and 10 entries, inclusive.
+ * This list MUST NOT have any duplicate entries. + */ + repeated PendingAirdropId pending_airdrops = 1; } diff --git a/sdk/src/main/proto/token_create.proto b/sdk/src/main/proto/token_create.proto index 43a545b5b..c07df160b 100644 --- a/sdk/src/main/proto/token_create.proto +++ b/sdk/src/main/proto/token_create.proto @@ -1,13 +1,21 @@ +/** + * # Token Create + * Create an Hedera Token Service (HTS) token. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,181 +39,319 @@ 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. - * - * 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. + * Create an HTS token. * - * 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. + * #### Keys + * Each token has several keys that, separately, control different functions + * for that token. It is *_strongly_* recommended that each key assigned to + * a token be unique, or disabled by assigning an empty `KeyList`. + * Keys and purpose + * - `adminKey` is a general access and may authorize a token update + * transaction as well as _update the other keys_. Even the admin key + * cannot authorize _adding_ a key that is not present, however.
+ * The admin key may also delete the token entirely. + * - `fee_schedule` may authorize updating the token custom fees. If this + * key is not present, the custom fees for the token are fixed and immutable. + * - `freeze` may authorize a token freeze or unfreeze transaction. + * If this key is not present, accounts holding this token cannot have + * their tokens frozen or unfrozen. + * - `kyc` may authorize a token grant KYC or revoke KYC transaction. + * If this key is not present, accounts holding this token cannot have + * KYC status granted or revoked. + * - `metadata` may authorize token update nfts transactions. + * If this key is not present, the token metadata values for that + * non-fungible/unique token _type_ will be immutable. + * - `pause` may authorize a token pause or token unpause transaction. + * If this key is not present, the token cannot be paused (preventing any + * account from transacting in that token) or resumed. + * - `supply` may authorize a token mint or burn transaction. + * If this key is not present, the token cannot mint additional supply and + * existing tokens cannot be "burned" from the treasury (but _might_ still be + * "burned" from individual accounts, c.f. `wipeKey` and `tokenWipe`). + * - `wipe` may authorize a token wipe account transaction. + * If this key is not present, accounts holding this token cannot have + * their balance or NFTs wiped (effectively burned). * - * 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. + * #### Requirements + * If `tokenType` is fungible/common, the `initialSupply` MUST be strictly + * greater than zero(`0`).
+ * If `tokenType` is non-fungible/unique, the `initialSupply` MUST + * be zero(`0`).
+ * If `tokenSupplyType` is "infinite", the `maxSupply` MUST be zero(`0`).
+ * If `tokenSupplyType` is "finite", the `maxSupply` MUST be strictly + * greater than zero(`0`).
* - * 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. + * ### Block Stream Effects + * If the token is created, the Token Identifier SHALL be in the receipt.
*/ message TokenCreateTransactionBody { /** - * The publicly visible name of the token. The token name is specified as a Unicode string. - * Its UTF-8 encoding cannot exceed 100 bytes, and cannot contain the 0 byte (NUL). + * A name for the token.
+ * This is generally the "full name" displayed in wallet software. + *

+ * This field is REQUIRED.
+ * This value MUST NOT exceed 100 bytes when encoded as UTF-8.
+ * This value MUST NOT contain the Unicode NUL codepoint. */ string name = 1; /** - * The publicly visible token symbol. The token symbol is specified as a Unicode string. - * Its UTF-8 encoding cannot exceed 100 bytes, and cannot contain the 0 byte (NUL). + * A symbol to use for the token. + *

+ * This field is REQUIRED.
+ * This value MUST NOT exceed 100 bytes when encoded as UTF-8.
+ * This value MUST NOT contain the Unicode NUL codepoint. */ string symbol = 2; /** - * 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 + * A decimal precision of the token's smallest denomination.
+ * Most values are described in terms of this smallest denomination, + * so the token initial supply, for instance, must be divided by + * 10decimals to get whole tokens. + *

+ * This MUST be zero(`0`) for non-fungible/unique tokens. */ uint32 decimals = 3; /** - * 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 + * An initial supply, in the smallest denomination for the token. + *

+ * This amount SHALL be transferred to the treasury account as part + * of this transaction.
+ * This amount MUST be specified in the smallest denomination for the + * token (i.e. 10-decimals whole tokens).
+ * This MUST be zero(`0`) for a non-fungible/unique token. */ uint64 initialSupply = 4; /** - * 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 + * A treasury account identifier. + *

+ * This field is REQUIRED.
+ * The identified account SHALL be designated the "treasury" for the + * new token, and all tokens "minted" SHALL be delivered to that account, + * including the initial supply, if any.
+ * The identified account MUST exist, MUST NOT be expired, and SHOULD + * have a non-zero HBAR balance.
+ * The identified account SHALL be associated to the new token. */ AccountID treasury = 5; /** - * 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) + * An Hedera key for token administration. + *

+ * This key, if set, SHALL have administrative authority for this token and + * MAY authorize token update and/or token delete transactions.
+ * If this key is not set, or is an empty `KeyList`, this token SHALL be + * immutable, except for expiration and renewal. */ Key adminKey = 6; /** - * 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. + * An Hedera key for managing account KYC. + *

+ * This key, if set, SHALL have KYC authority for this token and + * MAY authorize transactions to grant or revoke KYC for accounts.
+ * If this key is not set, or is an empty `KeyList`, KYC status for this + * token SHALL NOT be granted or revoked for any account.
+ * If this key is removed after granting KYC, those grants SHALL remain + * and cannot be revoked. */ Key kycKey = 7; /** - * The key which can sign to freeze or unfreeze an account for token transactions. If empty, - * freezing is not possible + * An Hedera key for managing asset "freeze". + *

+ * This key, if set, SHALL have "freeze" authority for this token and + * MAY authorize transactions to freeze or unfreeze accounts + * with respect to this token.
+ * If this key is not set, or is an empty `KeyList`, this token + * SHALL NOT be frozen or unfrozen for any account.
+ * If this key is removed after freezing accounts, those accounts + * SHALL remain frozen and cannot be unfrozen. */ Key freezeKey = 8; /** - * The key which can wipe the token balance of an account. If empty, wipe is not possible + * An Hedera key for wiping tokens from accounts. + *

+ * This key, if set, SHALL have "wipe" authority for this token and + * MAY authorize transactions to "wipe" any amount of this token from + * any account, effectively burning the tokens "wiped".
+ * If this key is not set, or is an empty `KeyList`, it SHALL NOT be + * possible to "wipe" this token from an account. */ Key wipeKey = 9; /** - * The key which can change the supply of a token. The key is used to sign Token Mint/Burn - * operations + * An Hedera key for "minting" and "burning" tokens. + *

+ * This key, if set, MAY authorize transactions to "mint" new tokens to + * be delivered to the token treasury or "burn" tokens held by the + * token treasury.
+ * If this key is not set, or is an empty `KeyList`, it SHALL NOT be + * possible to change the supply of tokens and neither "mint" nor "burn" + * transactions SHALL be permitted. */ Key supplyKey = 10; /** - * 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 + * An initial Freeze status for accounts associated to this token. + *

+ * If this value is set, an account MUST be the subject of a + * `tokenUnfreeze` transaction after associating to the token before + * that account can send or receive this token.
+ * If this value is set, the `freezeKey` SHOULD be set.
+ * If the `freezeKey` is not set, any account associated to this token + * while this value is set SHALL be permanently frozen. + *

+ *

REVIEW NOTE
+ * Should we prevent setting this value true for tokens with no freeze + * key?
+ * Should we set this value to false if a freeze key is removed? + *
*/ 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 + * An expiration timestamp. + *

+ * If the `autoRenewAccount` and `autoRenewPeriod` fields are set, this + * value SHALL be replaced with the current consensus time extended + * by the `autoRenewPeriod` duration.
+ * If this value is set and token expiration is enabled in network + * configuration, this token SHALL expire when consensus time exceeds + * this value, and MAY be subsequently removed from the network state.
+ * If this value is not set, and the automatic renewal account is also not + * set, then this value SHALL default to the current consensus time + * extended by the "default" expiration period from network configuration. */ Timestamp expiry = 13; /** - * An account which will be automatically charged to renew the token's expiration, at - * autoRenewPeriod interval + * An identifier for the account to be charged renewal fees at the token's + * expiry to extend the lifetime of the token. + *

+ * If this value is set, the token lifetime SHALL be extended by the + * _smallest_ of the following: + *

    + *
  • The current `autoRenewPeriod` duration.
    • + *
  • The maximum duration that this account has funds to purchase.
    • + *
  • The configured MAX_AUTORENEW_PERIOD at the time of automatic + * renewal.
    • + *
+ * If this account's HBAR balance is `0` when the token must be + * renewed, then the token SHALL be expired, and MAY be subsequently + * removed from state.
+ * If this value is set, the referenced account MUST sign this + * transaction. */ AccountID autoRenewAccount = 14; /** - * The interval at which the auto-renew account will be charged to extend the token's expiry + * A duration between token automatic renewals.
+ * All entities in state may be charged "rent" occasionally (typically + * every 90 days) to prevent unnecessary growth of the ledger. This value + * sets the interval between such events for this token. + *

+ * This value MUST be set.
+ * This value MUST be greater than the configured + * MIN_AUTORENEW_PERIOD.
+ * This value MUST be less than the configured MAX_AUTORENEW_PERIOD. */ Duration autoRenewPeriod = 15; /** - * The memo associated with the token (UTF-8 encoding max 100 bytes) + * A short description for this token. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 16; /** - * IWA compatibility. Specifies the token type. Defaults to FUNGIBLE_COMMON + * A type for this token, according to IWA classification. + *

+ * If this value is not set, the token SHALL have the default type of + * fungible/common.
+ * This field SHALL be immutable. */ TokenType tokenType = 17; /** - * IWA compatibility. Specified the token supply type. Defaults to INFINITE + * A supply type for this token, according to IWA classification. + *

+ * If this value is not set, the token SHALL have the default supply + * type of "infinite" (which is, as a practical matter, + * (263-1)/10decimals).
+ * This field SHALL be immutable. */ 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! + * A maximum supply for this token. + *

+ * This SHALL be interpreted in terms of the smallest fractional unit for + * this token.
+ * If `supplyType` is "infinite", this MUST be `0`.
+ * This field SHALL be immutable. */ int64 maxSupply = 19; /** - * The key which can change the token's custom fee schedule; must sign a TokenFeeScheduleUpdate - * transaction + * An Hedera key for managing the token custom fee schedule. + *

+ * This key, if set, MAY authorize transactions to modify the + * `custom_fees` for this token.
+ * If this key is not set, or is an empty `KeyList`, the `custom_fees` + * for this token SHALL NOT be modified. */ Key fee_schedule_key = 20; /** - * The custom fees to be assessed during a CryptoTransfer that transfers units of this token + * A list of custom fees representing a fee schedule. + *

+ * This list MAY be empty, which SHALL mean that there + * are no custom fees for this token.
+ * If this token is a non-fungible/unique type, the entries + * in this list MUST NOT declare a `fractional_fee`.
+ * If this token is a fungible/common type, the entries in this + * list MUST NOT declare a `royalty_fee`.
+ * Any token type MAY include entries that declare a `fixed_fee`. */ repeated CustomFee custom_fees = 21; /** - * The Key which can pause and unpause the Token. - * If Empty the token pause status defaults to PauseNotApplicable, otherwise Unpaused. + * An Hedera key for managing token "pause". + *

+ * This key, if set, SHALL have "pause" authority for this token and + * MAY authorize transactions to pause or unpause this token.
+ * If this key is not set, or is an empty `KeyList`, this token + * SHALL NOT be paused or unpaused.
+ * If this key is removed while the token is paused, the token cannot + * be unpaused and SHALL remain paused. */ Key pause_key = 22; /** - * Metadata of the created token definition. + * Token "Metadata". + *

+ * The value, if set, MUST NOT exceed 100 bytes.
+ *

Examples
+ *
hcs://1/0.0.4896575
+ *
ipfs://bafkreifd7tcjjuwxxf4qkaibkj62pj4mhfuud7plwrc3pfoygt55al6syi
+ *
*/ bytes metadata = 23; /** - * The key which can change the metadata of a token - * (token definition, partition definition, and individual NFTs). + * An Hedera key for managing the token `metadata`. + *

+ * This key, if set, MAY authorize transactions to modify the + * `metadata` for this token.
+ * If this key is not set, or is an empty `KeyList`, the `metadata` + * for this token SHALL NOT be modified. */ Key metadata_key = 24; } diff --git a/sdk/src/main/proto/token_delete.proto b/sdk/src/main/proto/token_delete.proto index 2f6f443f3..3737f7cb3 100644 --- a/sdk/src/main/proto/token_delete.proto +++ b/sdk/src/main/proto/token_delete.proto @@ -1,13 +1,21 @@ +/** + * # Token Delete + * Delete an Hedera Token Service (HTS) token. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,16 +36,38 @@ 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. + * Mark a token as deleted.
+ * A deleted token remains present in the network state, but is no longer + * active, cannot be held in a balance, and all operations on that token + * fail. A deleted token is removed from network state when it expires. + * + * #### Operations on a deleted token + * All operations on a deleted token SHALL fail with a + * status code `TOKEN_WAS_DELETED`.
+ * Any attempt to transfer a deleted token between accounts SHALL fail with + * a status code `TOKEN_WAS_DELETED`. + * + * > QUESTIONS + * >> What happens to existing balances/NFTs? + * >> Are these removed; are they stuck on the accounts? + * > + * >> If balances/NFTs remain, can a `tokenReject` remove them? + * + * #### Requirements + * The `admin_key` for the token MUST be set, and MUST + * sign this transaction.
+ * If the `admin_key` for the token is not set, this transaction SHALL + * fail with a status code `TOKEN_IS_IMMUTABlE`. + * + * ### Block Stream Effects + * None */ message TokenDeleteTransactionBody { /** - * The token to be deleted. If invalid token is specified, transaction will - * result in INVALID_TOKEN_ID + * A token identifier. + *

+ * This SHALL identify the token type to delete.
+ * The identified token MUST exist, and MUST NOT be deleted. */ TokenID token = 1; } diff --git a/sdk/src/main/proto/token_dissociate.proto b/sdk/src/main/proto/token_dissociate.proto index d51043091..a1f93d864 100644 --- a/sdk/src/main/proto/token_dissociate.proto +++ b/sdk/src/main/proto/token_dissociate.proto @@ -1,13 +1,22 @@ +/** + * # Token Dissociate + * Remove association between an account and one or more Hedera Token + * Service (HTS) tokens. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,30 +37,58 @@ 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. + * Dissociate an account from one or more HTS tokens. + * + * If the identified account is not found, + * the transaction SHALL return `INVALID_ACCOUNT_ID`.
+ * If the identified account has been deleted, + * the transaction SHALL return `ACCOUNT_DELETED`.
+ * If any of the identified tokens is not found, + * the transaction SHALL return `INVALID_TOKEN_REF`.
+ * If any of the identified tokens has been deleted, + * the transaction SHALL return `TOKEN_WAS_DELETED`.
+ * If an association does not exist for any of the identified tokens, + * the transaction SHALL return `TOKEN_NOT_ASSOCIATED_TO_ACCOUNT`.
+ * If the identified account has a nonzero balance for any of the identified + * tokens, and that token is neither deleted nor expired, the + * transaction SHALL return `TRANSACTION_REQUIRES_ZERO_TOKEN_BALANCES`.
+ * If one of the identified tokens is a fungible/common token that is expired, + * the account MAY disassociate from that token, even if that token balance is + * not zero for that account.
+ * If one of the identified tokens is a non-fungible/unique token that is + * expired, the account MUST NOT disassociate if that account holds any + * individual NFT of that token. In this situation the transaction SHALL + * return `TRANSACTION_REQUIRED_ZERO_TOKEN_BALANCES`.
+ * The identified account MUST sign this transaction. + * + * ### Block Stream Effects + * None */ message TokenDissociateTransactionBody { /** - * The account to be dissociated with the provided tokens + * An account identifier. + *

+ * The identified account SHALL be dissociated from each of the + * tokens identified in the `tokens` field. + * This field is REQUIRED and MUST be a valid account identifier.
+ * The identified account MUST exist in state.
+ * The identified account MUST NOT be deleted.
+ * The identified account MUST NOT be expired. */ AccountID account = 1; /** - * The tokens to be dissociated with the provided account + * A list of token identifiers. + *

+ * Each token identified in this list SHALL be dissociated from + * the account identified in the `account` field.
+ * This list MUST NOT be empty. + * Each entry in this list MUST be a valid token identifier.
+ * Each entry in this list MUST be currently associated to the + * account identified in `account`.
+ * Entries in this list MAY be expired, if the token type is + * fungible/common.
+ * Each entry in this list MUST NOT be deleted. */ repeated TokenID tokens = 2; } diff --git a/sdk/src/main/proto/token_fee_schedule_update.proto b/sdk/src/main/proto/token_fee_schedule_update.proto index 510189215..422f23571 100644 --- a/sdk/src/main/proto/token_fee_schedule_update.proto +++ b/sdk/src/main/proto/token_fee_schedule_update.proto @@ -1,13 +1,24 @@ +/** + * # Fee Schedule Update + * Transaction to update the fee schedule for a token. A token creator may + * wish to charge custom transaction fees for a token type, and if a + * `fee_schedule_key` is assigned, this transaction enables adding, removing, + * or updating those custom transaction fees. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +30,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -30,23 +40,38 @@ import "basic_types.proto"; import "custom_fees.proto"; /** - * At consensus, updates a token type's fee schedule to the given list of custom fees. + * Update the custom fee schedule for a token type. * - * 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. + * The token MUST have a `fee_schedule_key` set and that key MUST NOT + * be an empty `KeyList`.
+ * The token `fee_schedule_key` MUST sign this transaction.
+ * The token MUST exist, MUST NOT be deleted, and MUST NOT be expired.
* * 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. + * + * ### Block Stream Effects + * None */ message TokenFeeScheduleUpdateTransactionBody { /** - * The token whose fee schedule is to be updated + * A token identifier. + *

+ * This SHALL identify the token type to modify with an updated + * custom fee schedule.
+ * The identified token MUST exist, and MUST NOT be deleted. */ TokenID token_id = 1; /** - * The new custom fees to be assessed during a CryptoTransfer that transfers units of this token + * A list of custom fees representing a fee schedule. + *

+ * This list MAY be empty to remove custom fees from a token.
+ * If the identified token is a non-fungible/unique type, the entries + * in this list MUST NOT declare a `fractional_fee`.
+ * If the identified token is a fungible/common type, the entries in this + * list MUST NOT declare a `royalty_fee`.
+ * Any token type MAY include entries that declare a `fixed_fee`. */ repeated CustomFee custom_fees = 2; } diff --git a/sdk/src/main/proto/token_freeze_account.proto b/sdk/src/main/proto/token_freeze_account.proto index b25d64230..a81e6c0a1 100644 --- a/sdk/src/main/proto/token_freeze_account.proto +++ b/sdk/src/main/proto/token_freeze_account.proto @@ -1,13 +1,21 @@ +/** + * # Token Freeze Account + * Freeze all tokens of an identified type for an identified account. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,26 +36,44 @@ 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. + * Block transfers of a token type for an account.
+ * This, effectively, freezes assets of one account with respect to + * one token type. While frozen, that account cannot send or receive tokens + * of the identified type. + * + * The token MUST have a `freeze_key` set and that key MUST NOT + * be an empty `KeyList`.
+ * The token `freeze_key` MUST sign this transaction.
+ * The identified token MUST exist, MUST NOT be deleted, MUST NOT be paused, + * and MUST NOT be expired.
+ * The identified account MUST exist, MUST NOT be deleted, and + * MUST NOT be expired.
+ * If the identified account is already frozen with respect to the identified + * token, the transaction SHALL succeed, but no change SHALL be made.
+ * An association between the identified account and the identified + * token MUST exist. + * + * ### Block Stream Effects + * None */ message TokenFreezeAccountTransactionBody { /** - * The token for which this account will be frozen. If token does not exist, transaction results - * in INVALID_TOKEN_ID + * A token identifier. + *

+ * This SHALL identify the token type to "freeze".
+ * The identified token MUST exist, MUST NOT be deleted, and MUST be + * associated to the identified account. */ TokenID token = 1; /** - * The account to be frozen + * An account identifier. + *

+ * This shall identify the account to "freeze".
+ * The identified account MUST exist, MUST NOT be deleted, MUST NOT be + * expired, and MUST be associated to the identified token.
+ * The identified account SHOULD NOT be "frozen" with respect to the + * identified token. */ AccountID account = 2; } diff --git a/sdk/src/main/proto/token_get_account_nft_infos.proto b/sdk/src/main/proto/token_get_account_nft_infos.proto index 3a22091bc..9584fec23 100644 --- a/sdk/src/main/proto/token_get_account_nft_infos.proto +++ b/sdk/src/main/proto/token_get_account_nft_infos.proto @@ -1,13 +1,21 @@ +/** + * # Get Account NFT Infos + * Deprecated and permanently disabled + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,28 +39,16 @@ 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 - * - * 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 - * - * NOT_SUPPORTED response code will be returned if the queried token is of type FUNGIBLE_COMMON - * - * INVALID_ACCOUNT_ID response code will be returned if the queried account does not exist + * Deleted and unsupported. * - * ACCOUNT_DELETED response code will be returned if the queried account has been deleted + * This query is not implemented and any query of this type submitted + * SHALL return a `NOT_SUPPORTED` response code. */ message TokenGetAccountNftInfosQuery { /** - * 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 information sent with every query operation.
+ * This includes the signed payment and what kind of response is requested + * (cost, state proof, both, or neither). */ QueryHeader header = 1; @@ -63,25 +58,26 @@ message TokenGetAccountNftInfosQuery { 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] + * 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] + * 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 + * Deleted and unsupported. */ message TokenGetAccountNftInfosResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; diff --git a/sdk/src/main/proto/token_get_info.proto b/sdk/src/main/proto/token_get_info.proto index 12429c905..c130cb503 100644 --- a/sdk/src/main/proto/token_get_info.proto +++ b/sdk/src/main/proto/token_get_info.proto @@ -1,13 +1,21 @@ +/** + * # Get Token Info + * Query to retrieve information for a single token. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -34,225 +41,367 @@ import "timestamp.proto"; import "duration.proto"; /** - * Gets information about Token instance + * Request information for a token. */ message TokenGetInfoQuery { /** - * 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 information sent with every query operation.
+ * This includes 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. + * A token identifier. + *

+ * This SHALL identify the token to query.
+ * The identified token MUST exist, and MUST NOT be deleted. */ TokenID token = 2; } /** - * The metadata about a Token instance + * An Hedera Token Service(HTS) token. + * + * A token SHALL represent a fungible or non-fungible unit of exchange.
+ * The specified Treasury Account SHALL receive the initial supply of tokens and + * SHALL determine distribution of all tokens once minted. */ message TokenInfo { /** - * ID of the token instance + * A unique identifier for this token. */ TokenID tokenId = 1; /** - * The name of the token. It is a string of ASCII only characters + * A human-readable name for this token. + *

+ * This value MAY NOT be unique.
+ * This value SHALL NOT exceed 100 bytes when encoded as UTF-8. */ string name = 2; /** - * The symbol of the token. It is a UTF-8 capitalized alphabetical string + * A human-readable symbol for the token. + *

+ * This value SHALL NOT be unique.
+ * This value SHALL NOT exceed 100 bytes when encoded as UTF-8. */ string symbol = 3; /** - * The number of decimal places a token is divisible by. Always 0 for tokens of type - * NON_FUNGIBLE_UNIQUE + * A number of decimal places for this token. + *

+ * If decimals are 8 or 11, then the number of whole tokens can be at most + * billions or millions, respectively. More decimals allows for a more + * finely-divided token, but also limits the maximum total supply. + *

+ * Examples + *

    + *
  • Bitcoin satoshis (21 million whole tokens with 8 decimals).
    • + *
  • Hedera tinybar (50 billion whole tokens with 8 decimals).
    • + *
  • Bitcoin milli-satoshis (21 million whole tokens with 11 + * decimals).
    • + *
  • Theoretical limit is roughly 92.2 billion with 8 decimals, or + * 92.2 million with 11 decimals.
    • + *
+ * All token amounts in the network are stored as integer amounts, with + * each unit representing 10-decimals whole tokens. + *

+ * For tokens with `token_type` set to `NON_FUNGIBLE_UNIQUE` this MUST be 0. */ 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 + * A _current_ total supply of this token, expressed in the smallest unit + * of the token. + *

+ * The number of _whole_ tokens this represents is (total_supply / + * 10decimals). The value of total supply, MUST be within the + * positive range of a twos-compliment signed 64-bit integer. + * The `total_supply`, therefore MUST be between 1, and + * 9,223,372,036,854,775,807, inclusive. + *

+ * This value SHALL be reduced when a `token_burn` or `token_wipe_account` + * operation is executed, and SHALL be increased when a `token_mint` + * operation is executed. */ uint64 totalSupply = 5; /** - * The ID of the account which is set as Treasury + * A treasury account identifier for this token. + *

+ * When the token is created, the initial supply given in the token create + * transaction SHALL be minted and deposited in the treasury account.
+ * All token mint transactions for this token SHALL deposit the new minted + * tokens in the treasury account.
+ * All token burn transactions for this token SHALL remove the tokens to be + * burned from the treasury account. */ 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) + * Access control for general modification of this token. + *

+ * This key MUST sign any `token_update` transaction that + * changes any attribute of the token other than expiration_time. + * Other attributes of this token MAY be changed by transactions other than + * `token_update`, and MUST be signed by one of the other purpose-specific + * keys assigned to the token.
+ * This value can be set during token creation, and SHALL NOT be + * modified thereafter, unless the update transaction is signed by both + * the existing `admin_key` and the new `admin_key`.
+ * If the `admin_key` is not set for a token, that token SHALL be immutable. */ 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. + * Access control for KYC for this token. + *

+ * Know Your Customer (KYC) status may be granted for an account by a token + * grant kyc transaction signed by this key.
+ * If this key is not set, then KYC status cannot be granted to an account + * for this token, and any `TokenGrantKyc` transaction attempting to grant + * kyc to an account for this token SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key kycKey = 8; /** - * The key which can freeze or unfreeze an account for token transactions. If empty, freezing is - * not possible + * Access control to freeze this token. + *

+ * A token may be frozen for an account, preventing any transaction from + * transferring that token for that specified account, by a token freeze + * account transaction signed by this key.
+ * If this key is not set, the token cannot be frozen, and any transaction + * attempting to freeze the token for an account SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key freezeKey = 9; /** - * The key which can wipe token balance of an account. If empty, wipe is not possible + * Access control of account wipe for this token. + *

+ * A token may be wiped, removing and burning tokens from a specific + * account, by a token wipe transaction, which MUST be signed by this key. + * The `treasury_account` cannot be subjected to a token wipe. A token burn + * transaction, signed by the `supply_key`, serves to burn tokens held by + * the `treasury_account` instead.
+ * If this key is not set, the token cannot be wiped, and any transaction + * attempting to wipe the token from an account SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key wipeKey = 10; /** - * The key which can change the supply of a token. The key is used to sign Token Mint/Burn - * operations + * Access control of token mint/burn for this token. + *

+ * A token mint transaction MUST be signed by this key, and any token mint + * transaction not signed by the current `supply_key` for that token + * SHALL NOT succeed.
+ * A token burn transaction MUST be signed by this key, and any token burn + * transaction not signed by the current `supply_key` for that token + * SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ 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 + * A flag indicating if accounts associated to this token are frozen by + * default, not frozen, or freeze is not applicable. + *

+ * Accounts frozen by default and newly associated with this token CANNOT + * transact in the token until unfrozen.
+ * This SHALL NOT prevent a `tokenReject` transaction to return the tokens + * from an account to the treasury account. */ 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 + * A flag indicating if accounts associated with this token are granted + * KYC by default, revoked by default, or KYC is not applicable. */ TokenKycStatus defaultKycStatus = 13; /** - * Specifies whether the token was deleted or not + * A flag indicating that this token is deleted. + *

+ * A transaction involving a deleted token MUST NOT succeed. */ bool deleted = 14; /** - * An account which will be automatically charged to renew the token's expiration, at - * autoRenewPeriod interval + * An identifier for the account (if any) that the network will attempt + * to charge for this token's auto-renewal upon expiration. + *

+ * This field is OPTIONAL. If it is not set then renewal fees SHALL be + * charged to the account identified by `treasury`. */ AccountID autoRenewAccount = 15; /** - * The interval at which the auto-renew account will be charged to extend the token's expiry + * A duration by which the network should automatically extend + * this token's expiration. + *

+ * If the token has a valid auto-renew account, and is not deleted upon + * expiration, the network SHALL attempt to automatically renew this + * token.
+ * The default values for the minimum period and maximum period are 30 days + * and 90 days, respectively. */ Duration autoRenewPeriod = 16; /** - * The epoch second at which the token will expire + * An expiration time for this token, in seconds since the epoch. + *

+ * For this purpose, `epoch` SHALL be the + * UNIX epoch with 0 at `1970-01-01T00:00:00.000Z`. */ Timestamp expiry = 17; /** - * The memo associated with the token + * A short description of this token. + *

+ * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 18; /** - * The token type + * A type for this token. + *

+ * A token SHALL be either `FUNGIBLE_COMMON` or `NON_FUNGIBLE_UNIQUE`.
+ * If this value was omitted during token creation, `FUNGIBLE_COMMON` + * SHALL be used.
+ * The value `FUNGIBLE_COMMON` SHALL represent a fungible/common token. + * The value `NON_FUNGIBLE_UNIQUE` SHALL represent a + * non-fungible/unique token. */ TokenType tokenType = 19; /** - * The token supply type + * A supply type for this token. + *

+ * A token SHALL have either `INFINITE` or `FINITE` supply type.
+ * If this value was omitted during token creation, the value `INFINITE` + * SHALL be used. */ 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 + * A maximum supply of this token.
+ * This is the maximum number of tokens of this type that may be issued. + *

+ * This limit SHALL apply regardless of `token_type`.
+ * If `supply_type` is `INFINITE` then this value MUST be 0.
+ * If `supply_type` is `FINITE`, then this value MUST be greater than 0. */ int64 maxSupply = 21; /** - * The key which can change the custom fee schedule of the token; if not set, the fee schedule - * is immutable + * Access control of the `custom_fees` field for this token. + *

+ * The token custom fee schedule may be changed, modifying the fees charged + * for transferring that token, by a token update transaction, which MUST + * be signed by this key.
+ * If this key is not set, the token custom fee schedule cannot be changed, + * and any transaction attempting to change the custom fee schedule for + * this token SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key fee_schedule_key = 22; /** - * The custom fees to be assessed during a CryptoTransfer that transfers units of this token + * A custom fee schedule for this token. */ repeated CustomFee custom_fees = 23; /** - * The Key which can pause and unpause the Token. + * Access control of pause/unpause for this token. + *

+ * A token may be paused, preventing any transaction from transferring that + * token, by a token update transaction signed by this key.
+ * If this key is not set, the token cannot be paused, and any transaction + * attempting to pause the token SHALL NOT succeed.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ Key pause_key = 24; /** - * Specifies whether the token is paused or not. PauseNotApplicable is returned if pauseKey is not set. + * A flag indicating that this token is paused.
+ * A token may be paused, unpaused, or pause not applicable. + *

+ * A transaction involving a paused token, other than token_unpause, + * MUST NOT succeed. */ TokenPauseStatus pause_status = 25; /** - * The ledger ID the response was returned from; please see HIP-198 for the network-specific IDs. + * The ledger ID of the network that generated this response. + *

+ * This value SHALL identify the distributed ledger that responded to + * this query. */ bytes ledger_id = 26; /** - * Represents the metadata of the token definition. - */ - bytes metadata = 27; - - /** - * The key which can change the metadata of a token - * (token definition and individual NFTs). - */ - Key metadata_key = 28; - - /** - * A function-specific account key.
- * This key authorizes transactions to lock tokens in an account or account - * partition. - *

- * The key SHALL be used to authorize the locking and unlocking of tokens, - * or the transfer of locked tokens on balances held by the user - * on their account, or on the partition in their account. - */ - Key lock_key = 29; - - /** - * A function-specific account key.
- * This key authorizes transactions to partition fungible tokens and NFTs - * held by an account. + * A Token "Metadata". *

- * This key SHALL be used to authorize the creation, deletion, or updating - * of partition definitions owned by the token definition. + * This value, if set, SHALL NOT exceed 100 bytes. */ - Key partition_key = 30; + bytes metadata = 27; /** - * A function-specific account key.
- * This key authorizes transactions to move tokens between partitions. + * Access Control of metadata update for this token. *

- * This key SHALL be used to authorize the movement of tokens between - * partitions. + * A transaction to update the `metadata` field of this token MUST be + * signed by this key.
+ * If this token is a non-fungible/unique token type, a transaction to + * update the `metadata` field of any individual serialized unique token + * of this type MUST be signed by this key.
+ * If this key is not set, the token metadata SHALL NOT be changed after it + * is created.
+ * If this key is not set, the metadata for any individual serialized token + * of this type SHALL NOT be changed after it is created.
+ * This key MAY be set when the token is created, and MAY be set or modified + * via a token update transaction signed by the `admin_key`.
+ * If `admin_key` is not set, this value, whether set or unset, + * SHALL be immutable. */ - Key partition_move_key = 31; + Key metadata_key = 28; } /** - * Response when the client sends the node TokenGetInfoQuery + * A response message for the `getTokenInfo` query. */ message TokenGetInfoResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * The information requested about this token instance + * The information requested for the identified token. */ TokenInfo tokenInfo = 2; } diff --git a/sdk/src/main/proto/token_get_nft_info.proto b/sdk/src/main/proto/token_get_nft_info.proto index cf8df4cb8..cd7d05a75 100644 --- a/sdk/src/main/proto/token_get_nft_info.proto +++ b/sdk/src/main/proto/token_get_nft_info.proto @@ -1,13 +1,20 @@ +/** + * # Get NFT Info Query + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +26,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -37,23 +43,30 @@ import "timestamp.proto"; */ message TokenGetNftInfoQuery { /** - * 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 information sent with every query operation.
+ * This includes the signed payment and what kind of response is requested + * (cost, state proof, both, or neither). */ QueryHeader header = 1; /** - * The ID of the NFT + * A non-fungible/unique token (NFT) identifier. + *

+ * This SHALL identify the NFT to query.
+ * The identified NFT MUST exist, and MUST NOT be deleted. */ NftID nftID = 2; } /** - * UNDOCUMENTED + * Information for one non-fungible/unique token (NFT). + * */ message TokenNftInfo { /** - * The ID of the NFT + * A non-fungible/unique token (NFT) identifier. + *

+ * This SHALL match the NFT requested.
*/ NftID nftID = 1; @@ -73,7 +86,10 @@ message TokenNftInfo { bytes metadata = 4; /** - * The ledger ID the response was returned from; please see HIP-198 for the network-specific IDs. + * The ledger ID of the network that generated this response. + *

+ * This value SHALL identify the distributed ledger that responded to + * this query. */ bytes ledger_id = 5; @@ -88,8 +104,9 @@ message TokenNftInfo { */ message TokenGetNftInfoResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; diff --git a/sdk/src/main/proto/token_get_nft_infos.proto b/sdk/src/main/proto/token_get_nft_infos.proto index 7c782abcd..aefc02583 100644 --- a/sdk/src/main/proto/token_get_nft_infos.proto +++ b/sdk/src/main/proto/token_get_nft_infos.proto @@ -1,13 +1,21 @@ +/** + * # Token Get NFT Infos + * Deprecated and permanently disabled + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,61 +39,63 @@ 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 + * Deleted and unsupported. * - * 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 - * - * 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 + * This query is not implemented and any query of this type submitted + * SHALL return a `NOT_SUPPORTED` response code. */ message TokenGetNftInfosQuery { /** - * 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 information sent with every query operation.
+ * This includes 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 + * A token identifier. + *

+ * This SHALL identify the token to query.
+ * The identified token MUST exist, MUST NOT be deleted, and MUST be + * a non-fungible/unique type. */ 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] + * Specifies the start index (inclusive) of the range of NFTs to query for. + * Value must be in the range [0; mintedNFTs-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] + * Specifies the end index (exclusive) of the range of NFTs to query for. + * Value must be in the range (start; mintedNFTs] */ int64 end = 4; } +/** + * Deleted and unsupported. + */ message TokenGetNftInfosResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
+ * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; /** - * The Token with type NON_FUNGIBLE that this record is for + * A token identifier. + *

+ * This SHALL identify the token type to query.
+ * The identified token MUST exist, and MUST NOT be deleted. + * The identified token MUST be a non-fungible/unique type. */ TokenID tokenID = 2; /** - * List of NFTs associated to the specified token + * A list of messages, each of which describes one NFT. */ repeated TokenNftInfo nfts = 3; } diff --git a/sdk/src/main/proto/token_grant_kyc.proto b/sdk/src/main/proto/token_grant_kyc.proto index a45d4d109..0efb194a1 100644 --- a/sdk/src/main/proto/token_grant_kyc.proto +++ b/sdk/src/main/proto/token_grant_kyc.proto @@ -1,13 +1,30 @@ +/** + * # Token Grant KYC + * Grant "KYC" status to an account with respect to a token. + * + * The "KYC' property is named for the "Know Your Customer" requirements in + * US federal regulations (FINRA 2090 and related US Code) that was subsequently + * incorporated into laws and regulations for many worldwide jurisdictions. + * The process requires a regulated financial entity to positively identify + * customers and certain other entities. + * + * This transaction enables a token administrator to track whether KYC + * requirements are met for a given account transacting in that token. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +36,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,25 +45,38 @@ 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. + * Grant "Know Your Customer"(KYC) for one account for a single token. + * + * This transaction MUST be signed by the `kyc_key` for the token.
+ * The identified token MUST have a `kyc_key` set to a valid `Key` value.
+ * The token `kyc_key` MUST NOT be an empty `KeyList`.
+ * The identified token MUST exist and MUST NOT be deleted.
+ * The identified account MUST exist and MUST NOT be deleted.
+ * The identified account MUST have an association to the identified token.
+ * On success the association between the identified account and the identified + * token SHALL be marked as "KYC granted". + * + * ### Block Stream Effects + * None */ message TokenGrantKycTransactionBody { /** - * The token for which this account will be granted KYC. If token does not exist, transaction - * results in INVALID_TOKEN_ID + * A token identifier. + *

+ * The identified token SHALL grant "KYC" for the account + * identified by the `account` field.
+ * The identified token MUST be associated to the account identified + * by the `account` field. */ TokenID token = 1; /** - * The account to be KYCed + * An account identifier. + *

+ * The token identified by the `token` field SHALL grant "KYC" for the + * identified account.
+ * This account MUST be associated to the token identified + * by the `token` field. */ AccountID account = 2; } diff --git a/sdk/src/main/proto/token_mint.proto b/sdk/src/main/proto/token_mint.proto index bd2c499e7..6595f2a83 100644 --- a/sdk/src/main/proto/token_mint.proto +++ b/sdk/src/main/proto/token_mint.proto @@ -1,13 +1,22 @@ +/** + * # Token Mint + * Mint new tokens and deliver them to the token treasury. This is akin + * to how a fiat treasury will mint new coinage for circulation. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,40 +37,62 @@ 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 the metadata list is not filled for a non-fungible token type, a INVALID_TOKEN_MINT_AMOUNT response - * code will be returned. - * If a zero amount is provided for a fungible token type, it will be treated as a regular transaction. - * 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. + * Mint tokens and deliver the new tokens to the token treasury account. + * + * The token MUST have a `supply_key` set and that key MUST NOT + * be an empty `KeyList`.
+ * The token `supply_key` MUST sign this transaction.
+ * This operation SHALL increase the total supply for the token type by + * the number of tokens "minted".
+ * The total supply for the token type MUST NOT be increased above the + * maximum supply limit (2^63-1) by this transaction.
+ * The tokens minted SHALL be credited to the token treasury account.
+ * If the token is a fungible/common type, the amount MUST be specified.
+ * If the token is a non-fungible/unique type, the metadata bytes for each + * unique token MUST be specified in the `metadata` list.
+ * Each unique metadata MUST not exceed the global metadata size limit defined + * by the network configuration value `tokens.maxMetadataBytes`.
+ * The global batch size limit (`tokens.nfts.maxBatchSizeMint`) SHALL set + * the maximum number of individual NFT metadata permitted in a single + * `tokenMint` transaction. + * + * ### Block Stream Effects + * None */ message TokenMintTransactionBody { /** - * The token for which to mint tokens. If token does not exist, transaction results in - * INVALID_TOKEN_ID + * A token identifier. + *

+ * This SHALL identify the token type to "mint".
+ * The identified token MUST exist, and MUST NOT be deleted. */ 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. + * An amount to mint to the Treasury Account. + *

+ * This is interpreted as an amount in the smallest possible denomination + * for the token (10-decimals whole tokens).
+ * The balance for the token treasury account SHALL receive the newly + * minted tokens.
+ * If this value is equal to zero (`0`), the token SHOULD be a + * non-fungible/unique type.
+ * If this value is non-zero, the token MUST be a fungible/common type. */ 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 + * A list of metadata bytes.
+ *

+ * One non-fungible/unique token SHALL be minted for each entry + * in this list.
+ * Each entry in this list MUST NOT be larger than the limit set by the + * current network configuration value `tokens.maxMetadataBytes`.
+ * This list MUST NOT contain more entries than the current limit set by + * the network configuration value `tokens.nfts.maxBatchSizeMint`.
+ * If this list is not empty, the token MUST be a + * non-fungible/unique type.
+ * If this list is empty, the token MUST be a fungible/common type. */ repeated bytes metadata = 3; } diff --git a/sdk/src/main/proto/token_pause.proto b/sdk/src/main/proto/token_pause.proto index 55c33429e..3f21c11ae 100644 --- a/sdk/src/main/proto/token_pause.proto +++ b/sdk/src/main/proto/token_pause.proto @@ -1,13 +1,23 @@ +/** + * # Token Pause + * A transaction to "pause" all activity for a token. While a token is paused + * it cannot be transferred between accounts by any transaction other than + * `rejectToken`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +29,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,17 +38,26 @@ option java_multiple_files = true; import "basic_types.proto"; /** - * Pauses the Token from being involved in any kind of Transaction until it is unpaused. - * Must be signed with the Token's pause key. - * 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 no Pause Key is defined, the transaction will resolve to TOKEN_HAS_NO_PAUSE_KEY. - * Once executed the Token is marked as paused and will be not able to be a part of any transaction. - * The operation is idempotent - becomes a no-op if the Token is already Paused. + * Pause transaction activity for a token. + * + * This transaction MUST be signed by the Token `pause_key`.
+ * The `token` identified MUST exist, and MUST NOT be deleted.
+ * The `token` identified MAY be paused; if the token is already paused, + * this transaction SHALL have no effect. + * The `token` identified MUST have a `pause_key` set, the `pause_key` MUST be + * a valid `Key`, and the `pause_key` MUST NOT be an empty `KeyList`.
+ * A `paused` token SHALL NOT be transferred or otherwise modified except to + * "up-pause" the token with `unpauseToken` or in a `rejectToken` transaction. + * + * ### Block Stream Effects + * None */ message TokenPauseTransactionBody { /** - * The token to be paused. + * A token identifier. + *

+ * The identified token SHALL be paused. Subsequent transactions + * involving that token SHALL fail until the token is "unpaused". */ TokenID token = 1; } diff --git a/sdk/src/main/proto/token_reject.proto b/sdk/src/main/proto/token_reject.proto index d90f0051c..73b69f0ef 100644 --- a/sdk/src/main/proto/token_reject.proto +++ b/sdk/src/main/proto/token_reject.proto @@ -6,18 +6,17 @@ * ### Keywords * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119). + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ +/* * Copyright (C) 2024 Hedera Hashgraph, LLC - * ​ + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -29,7 +28,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -40,50 +38,68 @@ import "basic_types.proto"; /** * Reject undesired token(s).
- * Transfer one or more token balances held by the requesting account to the treasury for each - * token type.
+ * Transfer one or more token balances held by the requesting account to the + * treasury for each token type. + * * Each transfer SHALL be one of the following * - A single non-fungible/unique token. - * - The full balance held for a fungible/common token type. - * - * A single tokenReject transaction SHALL support a maximum of 10 transfers. + * - The full balance held for a fungible/common token. + * A single `tokenReject` transaction SHALL support a maximum + * of 10 transfers.
+ * A token that is `pause`d MUST NOT be rejected.
+ * If the `owner` account is `frozen` with respect to the identified token(s) + * the token(s) MUST NOT be rejected.
+ * The `payer` for this transaction, and `owner` if set, SHALL NOT be charged + * any custom fees or other fees beyond the `tokenReject` transaction fee. * - * ### Transaction Record Effects - * - Each successful transfer from `payer` to `treasury` SHALL be recorded in `token_transfer_list` for the transaction record. + * ### Block Stream Effects + * - Each successful transfer from `payer` to `treasury` SHALL be recorded in + * the `token_transfer_list` for the transaction record. */ message TokenRejectTransactionBody { - /** - * An account holding the tokens to be rejected.
- * If set, this account MUST sign this transaction. - * If not set, the payer for this transaction SHALL be the account rejecting tokens. - */ - AccountID owner = 1; + /** + * An account identifier.
+ * This OPTIONAL field identifies the account holding the + * tokens to be rejected. + *

+ * If set, this account MUST sign this transaction. + * If not set, the `payer` for this transaction SHALL be the effective + * `owner` for this transaction. + */ + AccountID owner = 1; - /** - * A list of one or more token rejections.
- * On success each rejected token serial number or balance SHALL be transferred from - * the requesting account to the treasury account for that token type.
- * After rejection the requesting account SHALL continue to be associated with the token.
- * if dissociation is desired then a separate TokenDissociate transaction MUST be submitted to remove the association. - */ - repeated TokenReference rejections = 2; + /** + * A list of one or more token rejections. + *

+ * On success each rejected token serial number or balance SHALL be + * transferred from the requesting account to the treasury account for + * that token type.
+ * After rejection the requesting account SHALL continue to be associated + * with the token.
+ * If dissociation is desired then a separate `TokenDissociate` transaction + * MUST be submitted to remove the association.
+ * This list MUST contain at least one (1) entry and MUST NOT contain more + * than ten (10) entries. + */ + repeated TokenReference rejections = 2; } /** * A union token identifier. * - * Identify a fungible/common token type, or a single non-fungible/unique token serial. + * Identify a fungible/common token type, or a single + * non-fungible/unique token serial. */ message TokenReference { - oneof token_identifier { - /** - * A fungible/common token type. - */ - TokenID fungible_token = 1; + oneof token_identifier { + /** + * A fungible/common token type. + */ + TokenID fungible_token = 1; - /** - * A single specific serialized non-fungible/unique token. - */ - NftID nft = 2; - } + /** + * A single specific serialized non-fungible/unique token. + */ + NftID nft = 2; + } } diff --git a/sdk/src/main/proto/token_relation.proto b/sdk/src/main/proto/token_relation.proto index aa594d92d..8bcef7d0a 100644 --- a/sdk/src/main/proto/token_relation.proto +++ b/sdk/src/main/proto/token_relation.proto @@ -1,13 +1,21 @@ +/** + * # Token Relationship. + * This is a connection between one Account, one _fungible_ Token, and + * associated balance within the Hedera network. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ import "basic_types.proto"; @@ -27,43 +34,105 @@ import "basic_types.proto"; option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; + /** - * Representation of a Hedera Token Service token relationship entity in the network Merkle tree. + * An Hedera Token Service token relationship. + * + * A token relationship connects an Account with a Token and is necessary for + * that Account to transact in that Token. TokenRelationship defines a + * connection between one account and one token type. + * + * A TokenRelation SHALL be identified by the combination of token_id and + * account_id.
+ * A TokenRelation SHALL contain, for the referenced token,
+ * The account's current balance, whether the account has KYC granted, + * and whether the assets are frozen. * - * As with all network entities, a token relationship has a unique entity number pair, which is represented - * with the account and the token involved in the relationship. + * TokenRelation entries SHALL be connected via a "virtual linked list" with the + * next TokenID and previous TokenID stored in the TokenRelation. + * These TokenIDs MUST be combined with the AccountID to find the next or + * previous relationship in the list. */ message TokenRelation { /** - * The token involved in this relation.It takes only positive + * A token identifier. + *

+ * This SHALL identify the token involved in this association. */ TokenID token_id = 1; + /** - * The account involved in this association. + * An account identifier. + *

+ * This SHALL identify the account involved in this association. */ AccountID account_id = 2; + /** - * The balance of the token relationship. + * The fungible token balance of this token relationship. + *

+ * This MUST be a whole number. */ int64 balance = 3; + /** - * The flags specifying the token relationship is frozen or not. + * A flag indicating that this token relationship is frozen. + *

+ * When a token relationship is frozen the associated account SHALL NOT be + * permitted to transfer to or from the associated balance. + *

+ * This flag is associated with the Token value `freeze_key`, and any + * transaction to set this flag MUST be signed by that key. If the Token + * does not have a `freeze_key` set, then this flag SHALL NOT be set true + * for relationships between accounts and that token. */ bool frozen = 4; + /** - * The flag indicating if the token relationship has been granted KYC. + * A flag indicating that this token relationship has been granted KYC status. + *

+ * If the token flag `accounts_kyc_granted_by_default` is set true, then + * this flag SHALL be set true for all accounts subsequently associated to + * that token. Otherwise this flag SHALL NOT be set until a transaction + * is submitted, and signed with the Token `kyc_key` to + * set the flag true.
+ * If the Token does not have a `kyc_key` set and the token flag + * `accounts_kyc_granted_by_default` is not set true, then this value MUST + * be false for all accounts subsequently associated to that token. + *

+ * Typically a transaction to set this value to true is considered + * equivalent to asserting that the "Know Your Customer" (KYC) requirements + * have been met for this combination of account and token and the relevant + * records are available as required. */ bool kyc_granted = 5; + /** - * The flag indicating if the token relationship was created using automatic association. + * A flag indicating that this token relationship was created using + * automatic association. + *

+ * If this is true then there MUST NOT exist a customer-signed transaction + * associating this account and token combination and the account + * `used_auto_associations` SHALL be incremented when this relationship + * is created. */ bool automatic_association = 6; + /** - * The previous token id of account's association linked list + * The Token ID of the previous entry in the associated Account's + * "virtual double-linked list" of token relationships. + *

+ * This must be combined with the value of `account_id` to identify the + * actual `TokenRelation` referenced. */ TokenID previous_token = 7; + /** - * The next token id of account's association linked list + * The Token ID of the next entry in the associated Account's "virtual + * double-linked list" of token relationships. + *

+ * This must be combined with the value of `account_id` to identify the + * actual `TokenRelation` referenced. */ TokenID next_token = 8; } diff --git a/sdk/src/main/proto/token_revoke_kyc.proto b/sdk/src/main/proto/token_revoke_kyc.proto index 5cb3bd099..cd666f440 100644 --- a/sdk/src/main/proto/token_revoke_kyc.proto +++ b/sdk/src/main/proto/token_revoke_kyc.proto @@ -1,13 +1,30 @@ +/** + * # Token Revoke KYC + * Revoke "KYC" status from an account with respect to a token. + * + * The "KYC' property is named for the "Know Your Customer" requirements in + * US federal regulations (FINRA 2090 and related US Code) that was subsequently + * incorporated into laws and regulations for many worldwide jurisdictions. + * The process requires a regulated financial entity to positively identify + * customers and certain other entities. + * + * This transaction enables a token administrator to track whether KYC + * requirements are met for a given account transacting in that token. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +36,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,25 +45,38 @@ 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 + * Revoke "Know Your Customer"(KYC) from one account for a single token. + * + * This transaction MUST be signed by the `kyc_key` for the token.
+ * The identified token MUST have a `kyc_key` set to a valid `Key` value.
+ * The token `kyc_key` MUST NOT be an empty `KeyList`.
+ * The identified token MUST exist and MUST NOT be deleted.
+ * The identified account MUST exist and MUST NOT be deleted.
+ * The identified account MUST have an association to the identified token.
+ * On success the association between the identified account and the identified + * token SHALL NOT be marked as "KYC granted". + * + * ### Block Stream Effects + * None */ message TokenRevokeKycTransactionBody { /** - * The token for which this account will get his KYC revoked. If token does not exist, - * transaction results in INVALID_TOKEN_ID + * A token identifier. + *

+ * The identified token SHALL revoke "KYC" for the account + * identified by the `account` field.
+ * The identified token MUST be associated to the account identified + * by the `account` field. */ TokenID token = 1; /** - * The account to be KYC Revoked + * An account identifier. + *

+ * The token identified by the `token` field SHALL revoke "KYC" for the + * identified account.
+ * This account MUST be associated to the token identified + * by the `token` field. */ AccountID account = 2; } diff --git a/sdk/src/main/proto/token_service.proto b/sdk/src/main/proto/token_service.proto index 65e30c9ec..f44adf1be 100644 --- a/sdk/src/main/proto/token_service.proto +++ b/sdk/src/main/proto/token_service.proto @@ -1,13 +1,21 @@ +/** + * # Token Service + * gRPC definitions for token service transactions. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -34,161 +41,194 @@ import "transaction.proto"; * Transactions and queries for the Token Service */ service TokenService { + // The following queries are permanently removed + // getAccountNftInfos, getTokenNftInfos + /** - * Creates a new Token by submitting the transaction + * Create a new token. */ rpc createToken (Transaction) returns (TransactionResponse); /** - * Updates the account by submitting the transaction + * Update a token. */ rpc updateToken (Transaction) returns (TransactionResponse); /** - * Mints an amount of the token to the defined treasury account + * Mint one or more tokens to the treasury account. + *

+ * This MAY specify a quantity of fungible/common tokens or + * a list of specific non-fungible/unique tokes, but + * MUST NOT specify both. */ rpc mintToken (Transaction) returns (TransactionResponse); /** - * Burns an amount of the token from the defined treasury account + * Burn one or more tokens from the treasury account. + *

+ * This MAY specify a quantity of fungible/common tokens or + * a list of specific non-fungible/unique tokes, but + * MUST NOT specify both. */ rpc burnToken (Transaction) returns (TransactionResponse); /** - * Deletes a Token + * Delete a token. */ rpc deleteToken (Transaction) returns (TransactionResponse); /** - * Wipes the provided amount of tokens from the specified Account ID + * Wipe one or more tokens from an identified Account. + *

+ * This MAY specify a quantity of fungible/common tokens or + * a list of specific non-fungible/unique tokes, but + * MUST NOT specify both. */ rpc wipeTokenAccount (Transaction) returns (TransactionResponse); /** - * Freezes the transfer of tokens to or from the specified Account ID + * Freeze the transfer of tokens to or from an identified Account. */ rpc freezeTokenAccount (Transaction) returns (TransactionResponse); /** - * Unfreezes the transfer of tokens to or from the specified Account ID + * Unfreeze the transfer of tokens to or from an identified Account. */ rpc unfreezeTokenAccount (Transaction) returns (TransactionResponse); /** - * Flags the provided Account ID as having gone through KYC + * Assert that KYC requirements are met for a specific account with + * respect to a specific token. */ rpc grantKycToTokenAccount (Transaction) returns (TransactionResponse); /** - * Removes the KYC flag of the provided Account ID + * Assert that KYC requirements are _not_ met for a specific account with + * respect to a specific token. */ rpc revokeKycFromTokenAccount (Transaction) returns (TransactionResponse); /** - * Associates tokens to an account + * Associate one or more tokens to an account. */ rpc associateTokens (Transaction) returns (TransactionResponse); /** - * Dissociates tokens from an account + * Dissociate one or more tokens from an account. */ rpc dissociateTokens (Transaction) returns (TransactionResponse); /** - * Updates the custom fee schedule on a token + * Update the custom fee schedule for a token. */ rpc updateTokenFeeSchedule (Transaction) returns (TransactionResponse); /** - * Retrieves the metadata of a token + * Retrieve the detail characteristics for a token. + *

+ * This query SHALL return information for the token type as a whole.
+ * This query SHALL NOT return information for individual tokens. */ rpc getTokenInfo (Query) returns (Response); /** - * (DEPRECATED) Gets info on NFTs N through M on the list of NFTs associated with a given account - */ - rpc getAccountNftInfos (Query) returns (Response) { - option deprecated = true; - }; - - /** - * Retrieves the metadata of an NFT by TokenID and serial number + * Retrieve the metadata for a specific non-fungible/unique token.
+ * The NFT to query is identified by token identifier and serial number. + *

+ * This query SHALL return token metadata and, if an allowance is defined, + * the designated "spender" account for the queried NFT. */ rpc getTokenNftInfo (Query) returns (Response); /** - * (DEPRECATED) Gets info on NFTs N through M on the list of NFTs associated with a given Token of type NON_FUNGIBLE + * Pause a token. */ - rpc getTokenNftInfos (Query) returns (Response) { - option deprecated = true; - }; - - // Pause the token rpc pauseToken (Transaction) returns (TransactionResponse); - // Unpause the token + /** + * Unpause (resume) a token. + */ rpc unpauseToken (Transaction) returns (TransactionResponse); /** - * Updates the NFTs in a collection by TokenID and serial number + * Update multiple non-fungible/unique tokens (NFTs) in a collection.
+ * The NFTs are identified by token identifier and one or more + * serial numbers. + *

+ * This transaction SHALL update NFT metadata only.
+ * This transaction MUST be signed by the token `metadata_key`. */ rpc updateNfts (Transaction) returns (TransactionResponse); /** - * Reject one or more tokens.
- * This transaction SHALL transfer the full balance of one or more tokens from the requesting - * account to the treasury for each token. This transfer SHALL NOT charge any custom fee or - * royalty defined for the token(s) to be rejected.
- *

Effects on success

+ * Reject one or more tokens. + *

+ * This transaction SHALL transfer the full balance of one or more tokens + * from the requesting account to the treasury for each token.
+ * This transfer SHALL NOT charge any custom fee or royalty defined for + * the token(s) to be rejected.
+ * ### Effects on success *

    - *
  • If the rejected token is fungible/common, the requesting account SHALL have a balance - * of 0 for the rejected token. The treasury balance SHALL increase by the amount that - * the requesting account decreased.
    • - *
  • If the rejected token is non-fungible/unique the requesting account SHALL NOT hold - * the specific serialized token that is rejected. The treasury account SHALL hold each - * specific serialized token that was rejected.
    • + *
  • If the rejected token is fungible/common, the requesting account + * SHALL have a balance of 0 for the rejected token.
    + * The treasury balance SHALL increase by the amount that the + * requesting account decreased.
    • + *
  • If the rejected token is non-fungible/unique the requesting + * account SHALL NOT hold the specific serialized token that + * is rejected.
    + * The treasury account SHALL hold each specific serialized token + * that was rejected.
    • * */ rpc rejectToken (Transaction) returns (TransactionResponse); /** - * Airdrop one or more tokens to one or more accounts.
    - * This distributes tokens from the balance of one or more sending account(s) to the balance - * of one or more recipient accounts. Accounts will receive the tokens in one of four ways. + * Airdrop one or more tokens to one or more accounts. + *

    + * This transaction SHALL distribute tokens from the balance of one or + * more sending account(s) to the balance of one or more + * recipient accounts.
    + * Accounts SHALL receive the tokens in one of four ways. *

      - *
    • An account already associated to the token to be distributed SHALL receive the - * airdropped tokens immediately to the recipient account balance.
      • - *
    • An account with available automatic association slots SHALL be automatically - * associated to the token, and SHALL immediately receive the airdropped tokens to the + *
    • An account already associated to the token to be distributed + * SHALL receive the airdropped tokens immediately to the * recipient account balance.
      • - *
    • An account with "receiver signature required" set SHALL have a "Pending Airdrop" - * created and MUST claim that airdrop with a `claimAirdrop` transaction.
      • - *
    • An account with no available automatic association slots SHALL have a - * "Pending Airdrop" created and MUST claim that airdrop with a `claimAirdrop` - * transaction.
      • + *
    • An account with available automatic association slots SHALL + * be automatically associated to the token, and SHALL + * immediately receive the airdropped tokens to the recipient + * account balance.
      • + *
    • An account with "receiver signature required" set SHALL have + * a "Pending Airdrop" created and MUST claim that airdrop with + * a `claimAirdrop` transaction.
      • + *
    • An account with no available automatic association slots SHALL + * have a "Pending Airdrop" created and MUST claim that airdrop + * with a `claimAirdrop` transaction.
      • *
    - * Any airdrop that completes immediately SHALL be irreversible. Any airdrop that results in a - * "Pending Airdrop" MAY be canceled via a `cancelAirdrop` transaction.
    - * All transfer fees (including custom fees and royalties), as well as the rent cost for the - * first auto-renewal period for any automatic-association slot occupied by the airdropped - * tokens, SHALL be charged to the account submitting this transaction. + * Any airdrop that completes immediately SHALL be irreversible.
    + * Any airdrop that results in a "Pending Airdrop" MAY be canceled via + * a `cancelAirdrop` transaction.
    + * All transfer fees (including custom fees and royalties), as well as + * the rent cost for the first auto-renewal period for any + * automatic-association slot occupied by the airdropped tokens, + * SHALL be charged to the account submitting this transaction. */ rpc airdropTokens (Transaction) returns (TransactionResponse); /** * Cancel one or more pending airdrops. *

    - * This transaction MUST be signed by _each_ account *sending* an airdrop to be canceled. + * This transaction MUST be signed by _each_ account *sending* an + * airdrop to be canceled. */ rpc cancelAirdrop (Transaction) returns (TransactionResponse); /** * Claim one or more pending airdrops. *

    - * This transaction MUST be signed by _each_ account **receiving** an - * airdrop to be claimed.
    - * If a "Sender" lacks sufficient balance to fulfill the airdrop at the - * time the claim is made, that claim SHALL fail. + * This transaction MUST be signed by _each_ account **receiving** + * an airdrop to be claimed.
    + * If a "Sender" lacks sufficient balance to fulfill the airdrop at + * the time the claim is made, that claim SHALL fail. */ rpc claimAirdrop (Transaction) returns (TransactionResponse); diff --git a/sdk/src/main/proto/token_unfreeze_account.proto b/sdk/src/main/proto/token_unfreeze_account.proto index d490d128f..73427c887 100644 --- a/sdk/src/main/proto/token_unfreeze_account.proto +++ b/sdk/src/main/proto/token_unfreeze_account.proto @@ -1,13 +1,21 @@ +/** + * # Token Unfreeze + * Release a freeze on tokens of an identified type for an identified account. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,27 +36,44 @@ 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. + * Resume transfers of a token type for an account.
    + * This releases previously frozen assets of one account with respect to + * one token type. Once unfrozen, that account can once again send or + * receive tokens of the identified type. + * + * The token MUST have a `freeze_key` set and that key MUST NOT + * be an empty `KeyList`.
    + * The token `freeze_key` MUST sign this transaction.
    + * The identified token MUST exist, MUST NOT be deleted, MUST NOT be paused, + * and MUST NOT be expired.
    + * The identified account MUST exist, MUST NOT be deleted, and + * MUST NOT be expired.
    + * If the identified account is not frozen with respect to the identified + * token, the transaction SHALL succeed, but no change SHALL be made.
    + * An association between the identified account and the identified + * token MUST exist. + * + * ### Block Stream Effects + * None */ message TokenUnfreezeAccountTransactionBody { /** - * The token for which this account will be unfrozen. If token does not exist, transaction - * results in INVALID_TOKEN_ID + * A token identifier. + *

    + * This SHALL identify the token type to "unfreeze".
    + * The identified token MUST exist, MUST NOT be deleted, and MUST be + * associated to the identified account. */ TokenID token = 1; /** - * The account to be unfrozen + * An account identifier. + *

    + * This shall identify the account to "unfreeze".
    + * The identified account MUST exist, MUST NOT be deleted, MUST NOT be + * expired, and MUST be associated to the identified token.
    + * The identified account SHOULD be "frozen" with respect to the + * identified token. */ AccountID account = 2; } diff --git a/sdk/src/main/proto/token_unpause.proto b/sdk/src/main/proto/token_unpause.proto index 5b32a8b19..26fa078cf 100644 --- a/sdk/src/main/proto/token_unpause.proto +++ b/sdk/src/main/proto/token_unpause.proto @@ -1,13 +1,24 @@ +/** + * # Token Un-Pause + * A transaction to "unpause" (i.e. resume) all activity for a token. While + * a token is "paused" it cannot be transferred between accounts by any + * transaction other than `rejectToken`. Once "unpaused", transactions involving + * that token may resume. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +30,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,16 +39,25 @@ option java_multiple_files = true; import "basic_types.proto"; /** - * Unpauses the Token. Must be signed with the Token's pause key. - * 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 no Pause Key is defined, the transaction will resolve to TOKEN_HAS_NO_PAUSE_KEY. - * Once executed the Token is marked as Unpaused and can be used in Transactions. - * The operation is idempotent - becomes a no-op if the Token is already unpaused. + * Resume transaction activity for a token. + * + * This transaction MUST be signed by the Token `pause_key`.
    + * The `token` identified MUST exist, and MUST NOT be deleted.
    + * The `token` identified MAY not be paused; if the token is not paused, + * this transaction SHALL have no effect. + * The `token` identified MUST have a `pause_key` set, the `pause_key` MUST be + * a valid `Key`, and the `pause_key` MUST NOT be an empty `KeyList`.
    + * An `unpaused` token MAY be transferred or otherwise modified. + * + * ### Block Stream Effects + * None */ message TokenUnpauseTransactionBody { /** - * The token to be unpaused. + * A token identifier. + *

    + * The identified token SHALL be "unpaused". Subsequent transactions + * involving that token MAY succeed. */ TokenID token = 1; } diff --git a/sdk/src/main/proto/token_update.proto b/sdk/src/main/proto/token_update.proto index af84e4dcd..7c2baf8a2 100644 --- a/sdk/src/main/proto/token_update.proto +++ b/sdk/src/main/proto/token_update.proto @@ -1,13 +1,23 @@ +/** + * # Token Update + * Modify the characteristics of an existing token. Most changes require that + * the transaction be signed by an `admin_key`, and if that key is not valid + * the only change permitted is to extend the token expiration. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +29,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,132 +41,279 @@ import "timestamp.proto"; import "google/protobuf/wrappers.proto"; /** - * At consensus, updates an already created token to the given values. + * Update an existing token. * - * 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. + * This transaction SHALL NOT update any field that is not set.
    + * Most changes MUST be signed by the current `admin_key` of the token. If the + * token does not currently have a valid `admin_key`, then this transaction + * MUST NOT set any value other than `expiry` or a non-admin key.
    + * If the `treasury` is set to a new account, the new account MUST sign this + * transaction.
    + * If the `treasury` is set to a new account for a _non-fungible/unique_ token, + * The current treasury MUST NOT hold any tokens, or the network configuration + * property `tokens.nfts.useTreasuryWildcards` MUST be set. * - * --- 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. + * #### Requirements for Keys + * Any of the key values may be changed, even without an admin key, but the + * key to be changed MUST have an existing valid key assigned, and both the + * current key and the new key MUST sign the transaction.
    + * A key value MAY be set to an empty `KeyList`. In this case the existing + * key MUST sign this transaction, but the new value is not a valid key, and the + * update SHALL effectively remove the existing key. * - * --- Nft Requirements --- - * 1. If a non fungible token has a positive treasury balance, the operation will abort with - * CURRENT_TREASURY_STILL_OWNS_NFTS. + * ### Block Stream Effects + * None */ message TokenUpdateTransactionBody { /** - * The Token to be updated + * A token identifier. + *

    + * This SHALL identify the token type to delete.
    + * The identified token MUST exist, and MUST NOT be deleted.
    + * If any field other than `expiry` is set, the identified token MUST + * have a valid `admin_key`. */ TokenID token = 1; /** - * The new publicly visible token symbol. The token symbol is specified as a Unicode string. - * Its UTF-8 encoding cannot exceed 100 bytes, and cannot contain the 0 byte (NUL). + * A new symbol to use for the token. + *

    + * This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.
    + * This value, if set, MUST NOT contain the Unicode NUL codepoint. */ string symbol = 2; /** - * The new publicly visible name of the token. The token name is specified as a Unicode string. - * Its UTF-8 encoding cannot exceed 100 bytes, and cannot contain the 0 byte (NUL). + * A new name for the token.
    + * This is generally the "full name" displayed in wallet software. + *

    + * This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.
    + * This value, if set, MUST NOT contain the Unicode NUL codepoint. */ string name = 3; /** - * 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. + * A new treasury account identifier. + *

    + * If set, + * - The identified account SHALL be designated the "treasury" for the + * token, and all tokens "minted" SHALL be delivered to that account + * following this transaction.
    + * - The identified account MUST exist, MUST NOT be expired, MUST NOT be + * deleted, and SHOULD have a non-zero HBAR balance.
    + * - The identified account SHALL be associated to this token. + * - The full balance of this token held by the prior treasury account + * SHALL be transferred to the new treasury account, if the token type + * is fungible/common. + * - If the token type is non-fungible/unique, the previous treasury + * account MUST NOT hold any tokens of this type. + * - The new treasury account key MUST sign this transaction. */ AccountID treasury = 4; /** - * The new admin key of the Token. If Token is immutable, transaction will resolve to - * TOKEN_IS_IMMUTABlE. + * An Hedera key for token administration. + *

    + * This key, if set, SHALL have administrative authority for this token and + * MAY authorize token update and/or token delete transactions.
    + * If this key is set to an empty `KeyList`, this token SHALL be + * immutable thereafter, except for expiration and renewal.
    + * If set, this key MUST be a valid key or an empty `KeyList`.
    + * If set to a valid key, the previous key and new key MUST both + * sign this transaction. */ 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. + * An Hedera key for managing account KYC. + *

    + * This key, if set, SHALL have KYC authority for this token and + * MAY authorize transactions to grant or revoke KYC for accounts.
    + * If this key is not set, or is an empty `KeyList`, KYC status for this + * token SHALL NOT be granted or revoked for any account.
    + * If this key is removed after granting KYC, those grants SHALL remain + * and cannot be revoked.
    + * If set, this key MUST be a valid key or an empty `KeyList`.
    + * If set to a valid key, the previous key and new key MUST both + * sign this transaction. */ 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. + * An Hedera key for managing asset "freeze". + *

    + * This key, if set, SHALL have "freeze" authority for this token and + * MAY authorize transactions to freeze or unfreeze accounts + * with respect to this token.
    + * If this key is set to an empty `KeyList`, this token + * SHALL NOT be frozen or unfrozen for any account.
    + * If this key is removed after freezing accounts, those accounts + * SHALL remain frozen and cannot be unfrozen.
    + * If set, this key MUST be a valid key or an empty `KeyList`.
    + * If set to a valid key, the previous key and new key MUST both + * sign this transaction. */ 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. + * An Hedera key for wiping tokens from accounts. + *

    + * This key, if set, SHALL have "wipe" authority for this token and + * MAY authorize transactions to "wipe" any amount of this token from + * any account, effectively burning the tokens "wiped".
    + * If this key is set to an empty `KeyList`, it SHALL NOT be + * possible to "wipe" this token from an account.
    + * If set, this key MUST be a valid key or an empty `KeyList`.
    + * If set to a valid key, the previous key and new key MUST both + * sign this transaction. */ 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. + * An Hedera key for "minting" and "burning" tokens. + *

    + * This key, if set, MAY authorize transactions to "mint" new tokens to + * be delivered to the token treasury or "burn" tokens held by the + * token treasury.
    + * If this key is set to an empty `KeyList`, it SHALL NOT be + * possible to change the supply of tokens and neither "mint" nor "burn" + * transactions SHALL be permitted.
    + * If set, this key MUST be a valid key or an empty `KeyList`.
    + * If set to a valid key, the previous key and new key MUST both + * sign this transaction. */ Key supplyKey = 9; /** - * The new account which will be automatically charged to renew the token's expiration, at - * autoRenewPeriod interval. + * An identifier for the account to be charged renewal fees at the token's + * expiry to extend the lifetime of the token. + *

    + * If this value is set for the identified token, the token lifetime SHALL + * be extended by the _smallest_ of the following at expiration: + *

      + *
    • The current `autoRenewPeriod` duration.
      • + *
    • The maximum duration that this account has funds to purchase.
      • + *
    • The configured MAX_AUTORENEW_PERIOD at the time of automatic + * renewal.
      • + *
    + * If this account's HBAR balance is `0` when the token must be + * renewed, then the token SHALL be expired, and MAY be subsequently + * removed from state.
    + * If this value is set, the referenced account MUST sign this + * transaction. + *

    + *

    Note
    + * It is not currently possible to remove an automatic renewal account. + * Once set, it can only be replaced by a valid account. + *
    */ AccountID autoRenewAccount = 10; /** - * The new interval at which the auto-renew account will be charged to extend the token's - * expiry. + * A duration between token automatic renewals.
    + * All entities in state may be charged "rent" occasionally (typically + * every 90 days) to prevent unnecessary growth of the ledger. This value + * sets the interval between such events for this token. + *

    + * If set, this value MUST be greater than the configured + * `MIN_AUTORENEW_PERIOD`.
    + * If set, this value MUST be less than the configured + * `MAX_AUTORENEW_PERIOD`. */ 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 + * An expiration timestamp. + *

    + * If this value is set, the automatic renewal account is not set for the + * identified token, and token expiration is enabled in network + * configuration, this token SHALL expire when the consensus time exceeds + * this value, and MAY be subsequently removed from the network state.
    + * If `autoRenewAccount` is set or the `auto_renew_account_id` is set for + * the identified token, the token SHALL be subject to automatic renewal + * when the consensus time exceeds this value. */ Timestamp expiry = 12; /** - * If set, the new memo to be associated with the token (UTF-8 encoding max 100 bytes) + * A short description for this token. + *

    + * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ 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 + * An Hedera key for managing the token custom fee schedule. + *

    + * This key, if set, MAY authorize transactions to modify the + * `custom_fees` for this token.
    + * If this key is set to an empty `KeyList`, the `custom_fees` + * for this token SHALL NOT be modified.
    + * If set, this key MUST be a valid key or an empty `KeyList`.
    + * If set to a valid key, the previous key and new key MUST both + * sign this transaction. */ Key fee_schedule_key = 14; /** - * The Key which can pause and unpause the Token. If the Token does not currently have a pause key, - * transaction will resolve to TOKEN_HAS_NO_PAUSE_KEY + * An Hedera key for managing token "pause". + *

    + * This key, if set, SHALL have "pause" authority for this token and + * MAY authorize transactions to pause or unpause this token.
    + * If this key is set to an empty `KeyList`, this token + * SHALL NOT be paused or unpaused.
    + * If this key is removed while the token is paused, the token cannot + * be unpaused and SHALL remain paused.
    + * If set, this key MUST be a valid key or an empty `KeyList`.
    + * If set to a valid key, the previous key and new key MUST both + * sign this transaction. */ Key pause_key = 15; /** - * Metadata of the created token definition + * Token "Metadata". + *

    + * The value, if set, MUST NOT exceed 100 bytes.
    + *

    Examples
    + *
    hcs://1/0.0.4896575
    + *
    ipfs://bafkreifd7tcjjuwxxf4qkaibkj62pj4mhfuud7plwrc3pfoygt55al6syi
    + *
    */ google.protobuf.BytesValue metadata = 16; /** - * The key which can change the metadata of a token - * (token definition, partition definition, and individual NFTs). - * If the Token does not have currently a Metadata key, - * transaction will resolve to TOKEN_HAS_NO_METADATA_KEY + * An Hedera key for managing the token `metadata`. + *

    + * This key, if set, MAY authorize transactions to modify the + * `metadata` for this token.
    + * If this key is set to an empty `KeyList`, the `metadata` + * for this token SHALL NOT be modified.
    + * If set, this key MUST be a valid key or an empty `KeyList`.
    + * If set to a valid key, the previous key and new key MUST both + * sign this transaction. */ Key metadata_key = 17; /** - * Determines whether the system should check the validity of the passed keys for update. + * Set a key validation mode.
    + * Any key may be updated by a transaction signed by the token `admin_key`. + * Each role key may _also_ sign a transaction to update that key. + * If a role key signs an update to change that role key both old + * and new key must sign the transaction, _unless_ this field is set + * to `NO_VALIDATION`, in which case the _new_ key is not required to + * sign the transaction (the existing key is still required).
    + * The primary intent for this field is to allow a role key (e.g. a + * `pause_key`) holder to "remove" that key from the token by signing + * a transaction to set that role key to an empty `KeyList`. + *

    + * If set to `FULL_VALIDATION`, either the `admin_key` or _both_ current + * and new key MUST sign this transaction to update a "key" field for the + * identified token.
    + * If set to `NO_VALIDATION`, either the `admin_key` or the current + * key MUST sign this transaction to update a "key" field for the + * identified token.
    + * This field SHALL be treated as `FULL_VALIDATION` if not set. */ TokenKeyValidation key_verification_mode = 18; } diff --git a/sdk/src/main/proto/token_update_nfts.proto b/sdk/src/main/proto/token_update_nfts.proto index a5ede209c..f90555e90 100644 --- a/sdk/src/main/proto/token_update_nfts.proto +++ b/sdk/src/main/proto/token_update_nfts.proto @@ -1,3 +1,15 @@ +/** + * # Token Update NFTs + * Given a token identifier and a metadata block, change the metadata for + * one or more non-fungible/unique token instances. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; @@ -26,30 +38,45 @@ import "basic_types.proto"; import "google/protobuf/wrappers.proto"; /** - * At consensus, updates an already created Non Fungible Token to the given values. - * - * If no value is given for a field, that field is left unchanged. - * Only certain fields such as metadata can be updated. + * Modify the metadata field for an individual non-fungible/unique token (NFT). * - * Updating the metadata of an NFT does not affect its ownership or transferability. - * This operation is intended for updating attributes of individual NFTs in a collection. + * Updating the metadata of an NFT SHALL NOT affect ownership or + * the ability to transfer that NFT.
    + * This transaction SHALL affect only the specific serial numbered tokens + * identified. + * This transaction SHALL modify individual token metadata.
    + * This transaction MUST be signed by the token `metadata_key`.
    + * The token `metadata_key` MUST be a valid `Key`.
    + * The token `metadata_key` MUST NOT be an empty `KeyList`. * - * --- Signing Requirements --- - * 1. To update metadata of an NFT, the metadata_key of the token should sign the transaction. + * ### Block Stream Effects + * None */ message TokenUpdateNftsTransactionBody { /** - * The token for which to update NFTs. + * A token identifier.
    + * This is the token type (i.e. collection) for which to update NFTs. + *

    + * This field is REQUIRED.
    + * The identified token MUST exist, MUST NOT be paused, MUST have the type + * non-fungible/unique, and MUST have a valid `metadata_key`. */ TokenID token = 1; /** - * The list of serial numbers to be updated. + * A list of serial numbers to be updated. + *

    + * This field is REQUIRED.
    + * This list MUST have at least one(1) entry.
    + * This list MUST NOT have more than ten(10) entries. */ repeated int64 serial_numbers = 2; /** - * The new metadata of the NFT(s) + * A new value for the metadata. + *

    + * If this field is not set, the metadata SHALL NOT change.
    + * This value, if set, MUST NOT exceed 100 bytes. */ google.protobuf.BytesValue metadata = 3; } diff --git a/sdk/src/main/proto/token_wipe_account.proto b/sdk/src/main/proto/token_wipe_account.proto index 3d237a6eb..b60ac9f28 100644 --- a/sdk/src/main/proto/token_wipe_account.proto +++ b/sdk/src/main/proto/token_wipe_account.proto @@ -1,13 +1,21 @@ +/** + * # Token Wipe Account + * Administratively burn tokens owned by a single, non-treasury, account. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,55 +36,89 @@ 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. + * Wipe (administratively burn) tokens held by a non-treasury account.
    + * On success, the requested tokens will be removed from the identified account + * and the token supply will be reduced by the amount "wiped". * - * If both amount and serialNumbers get filled, a INVALID_TRANSACTION_BODY response code will be - * returned. - * If the serialNumbers don't get filled for a non-fungible token type, a INVALID_WIPING_AMOUNT response - * code will be returned. - * If a zero amount is provided for a fungible token type, it will be treated as a regular transaction. - * 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. + * This transaction MUST be signed by the token `wipe_key`.
    + * The identified token MUST exist, MUST NOT be deleted, + * and MUST NOT be paused.
    + * The identified token MUST have a valid `Key` set for the `wipe_key` field, + * and that key MUST NOT be an empty `KeyList`.
    + * The identified account MUST exist, MUST NOT be deleted, MUST be + * associated to the identified token, MUST NOT be frozen for the identified + * token, MUST NOT be the token `treasury`, and MUST hold a balance for the + * token or the specific serial numbers provided.
    + * This transaction SHOULD provide a value for `amount` or `serialNumbers`, + * but MUST NOT set both fields. * - * 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. + * ### Block Stream Effects + * The new total supply for the wiped token type SHALL be recorded. */ message TokenWipeAccountTransactionBody { /** - * The token for which the account will be wiped. If token does not exist, transaction results - * in INVALID_TOKEN_ID + * A token identifier. + *

    + * This field is REQUIRED.
    + * The identified token MUST exist, MUST NOT be paused, MUST NOT be + * deleted, and MUST NOT be expired. */ TokenID token = 1; /** - * The account to be wiped + * An account identifier.
    + * This identifies the account from which tokens will be wiped. + *

    + * This field is REQUIRED.
    + * The identified account MUST NOT be deleted or expired.
    + * If the identified token `kyc_key` is set to a valid key, the + * identified account MUST have "KYC" granted.
    + * The identified account MUST NOT be the `treasury` account for the + * identified token. */ 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] + * An amount of fungible/common tokens to wipe. + *

    + * If the identified token is a non-fungible/unique token type, + * this value MUST be exactly zero(`0`).
    + * If the identified token type is fungible/common: + *

      + *
    • This value SHALL be specified in units of the smallest + * denomination possible for the identified token + * (10-decimals whole tokens).
      • + *
    • This value MUST be strictly less than `Long.MAX_VALUE`.
      • + *
    • This value MUST be less than or equal to the current total + * supply for the identified token.
      • + *
    • This value MUST be less than or equal to the current balance + * held by the identified account.
      • + *
    • This value MAY be zero(`0`).
      • + *
    */ uint64 amount = 3; /** - * Applicable to tokens of type NON_FUNGIBLE_UNIQUE. The list of serial numbers to be wiped. + * A list of serial numbers to wipe.
    + * The non-fungible/unique tokens with these serial numbers will be + * destroyed and cannot be recovered or reused. + *

    + * If the identified token type is a fungible/common type, this + * list MUST be empty.
    + * If the identified token type is non-fungible/unique: + *

      + *
    • This list MUST contain at least one entry if the identified token + * type is non-fungible/unique.>/li> + *
    • This list MUST NOT contain more entries than the current total + * supply for the identified token.
      • + *
    • Every entry in this list MUST be a valid serial number for the + * identified token (i.e. "collection").
      • + *
    • Every entry in this list MUST be owned by the + * identified account
      • + *
    • + *
    + * This list MUST NOT contain more entries than the network configuration + * value for batch size limit, typically ten(`10`). */ repeated int64 serialNumbers = 4; } diff --git a/sdk/src/main/proto/topic.proto b/sdk/src/main/proto/topic.proto index ab7359273..91b1bde93 100644 --- a/sdk/src/main/proto/topic.proto +++ b/sdk/src/main/proto/topic.proto @@ -1,13 +1,20 @@ +/** + * # HCS Topic Information + * The current network state of an Hedera Consensus Service (HCS) Topic. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119) + * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2023 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2023-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,83 +26,169 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ import "basic_types.proto"; +import "custom_fees.proto"; option java_package = "com.hedera.hashgraph.sdk.proto"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; /** - * Representation of a Hedera Consensus Service topic in the network Merkle tree. - * - * As with all network entities, a topic has a unique entity number, which is usually given along - * with the network's shard and realm in the form of a shard.realm.number id. + * Representation of an Hedera Consensus Service(HCS) topic. * - * A topic consists of just two pieces of data: - * 1. The total number of messages sent to the topic; and, - * 2. The running hash of all those messages. - * It also has several metadata elements: - * 1. A consensus expiration time in seconds since the epoch. - * 2. (Optional) The number of an auto-renew account, in the same shard and realm as the topic, that - * has signed a transaction allowing the network to use its balance to automatically extend the topic's - * expiration time when it passes. - * 3. The number of seconds the network should automatically extend the topic's expiration by, if the - * topic has a valid auto-renew account, and is not deleted upon expiration. - * 4. A boolean marking if the topic has been deleted. - * 5. A memo string whose UTF-8 encoding is at most 100 bytes. - * 6. (Optional) An admin key whose signature must be active for the topic's metadata to be updated. - * 7. (Optional) A submit key whose signature must be active for the topic to receive a message. + * As with all network entities, a topic has a unique entity number, which is + * usually given along with the network's shard and realm in the form of a + * shard.realm.number id.
    + * An HCS topic is an ordered logical stream of messages united and secured by + * a running hash of those messages. The integrity of any message on a topic, + * and the topic stream as a whole, can always be ascertained from block stream + * data by recomputing the running hash across any subset of messages on the + * topic.
    + * The messages on a topic SHALL NOT be stored in network state, but are + * available in the network block stream, and may be queried via the + * Mirror Node system. */ message Topic { /** - * The topic's unique id in the Merkle state. + * The topic's ID. + *

    + * This value SHALL be unique within the network. */ TopicID topic_id = 1; + /** * The number of messages sent to the topic. */ int64 sequence_number = 2; + /** - * The topic's consensus expiration time in seconds since the epoch. + * The expiration time for this topic, in seconds since the epoch. + *

    + * For this purpose, `epoch` SHALL be the UNIX epoch with 0 at `1970-01-01T00:00:00.000Z`. */ int64 expiration_second = 3; + /** * The number of seconds for which the topic will be automatically renewed * upon expiring (if it has a valid auto-renew account). */ int64 auto_renew_period = 4; + /** - * The id of the account (if any) that the network will attempt to charge for the - * topic's auto-renewal upon expiration. + * The id of the account (if any) that the network will attempt to charge + * fees to complete auto-renewal of this topic, upon expiration. */ AccountID auto_renew_account_id = 5; + /** - * Whether this topic is deleted. + * A flag indicating that this topic is deleted. */ bool deleted = 6; + /** - * 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 current running hash of this topic. + *

    + * This 48-byte field is the output of a SHA-384 digest with input data + * determined by the current version of the running hash algorithm used + * by the network.
    + * All topics in state SHALL use running hash algorithm version `3`.
    + * The bytes of each uint64 or uint32 encoded for the hash input MUST be in + * Big-Endian format. + *

    + *

    + * If the algorithm version 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. + *
    2. The `topicRunningHashVersion` (8 bytes)
      3. + *
    3. The payer account's shard (8 bytes)
      4. + *
    4. The payer account's realm (8 bytes)
      5. + *
    5. The payer account's number (8 bytes)
      6. + *
    6. The topic's shard (8 bytes)
      7. + *
    7. The topic's realm (8 bytes)
      8. + *
    8. The topic's number (8 bytes)
      9. + *
    9. The number of seconds since the epoch when the + * `ConsensusSubmitMessage` reached consensus (8 bytes)
      10. + *
    10. The number of nanoseconds within the second when the + * `ConsensusSubmitMessage` reached consensus (4 bytes)
      11. + *
    11. The `topicSequenceNumber` (8 bytes)
      12. + *
    12. The output of a SHA-384 digest of the message bytes from the + * `ConsensusSubmitMessage` (48 bytes)
      13. + *
    + *
    Note that older messages on a topic, which are available in + * the block stream, MAY use older algorithm versions, and the block stream + * record incorporates a running hash version field to ensure the correct + * hash calculation for each such historical message.
    */ bytes running_hash = 7; + /** - * An optional description of the topic with UTF-8 encoding up to 100 bytes. + * A short description of this topic. + *

    + * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 8; + /** - * If present, enforces access control for updating or deleting the topic. - * A topic without an admin key is immutable. + * Access control for modification of the topic. + *

    + * If this field is set, that key MUST sign each message to update or delete + * this topic.
    + * A topic without an admin key SHALL be immutable, except for expiration + * and renewal.
    + * If this field is not set, the `auto_renew_account_id` MUST NOT be set. */ Key admin_key = 9; + /** - * If present, enforces access control for message submission to the topic. + * Access control for message submission to the topic. + *

    + * If this field is set, that key MUST sign each consensus submit message + * for this topic. */ Key submit_key = 10; + + /** + * Access control for update/delete of custom fees. + *

    + * If this field is unset, the current custom fees CANNOT be changed.
    + * If this field is set, that `Key` MUST sign any transaction to update + * the custom fee schedule for this topic. + */ + Key fee_schedule_key = 11; + + /** + * A set of "privileged payer" keys
    + * Keys in this list are permitted to submit messages to this topic without + * paying custom fees associated with this topic. + *

    + * If a submit transaction is signed by _any_ key included in this set, + * custom fees SHALL NOT be charged for that transaction.
    + * A `fee_exempt_key_list` MUST NOT contain more than + * `MAX_ENTRIES_FOR_FEE_EXEMPT_KEY_LIST` keys.
    + * A `fee_exempt_key_list` MUST NOT contain any duplicate keys.
    + * A `fee_exempt_key_list` MAY contain keys for accounts that are inactive, + * deleted, or non-existent. + * If not set, there SHALL NOT be any fee-exempt keys. In particular, the + * following keys SHALL NOT be implicitly or automatically added to this + * list: `adminKey`, `submitKey`, `fee_schedule_key`. + */ + repeated Key fee_exempt_key_list = 12; + + /** + * A set of custom fee definitions.
    + * These are fees to be assessed for each submit to this topic. + *

    + * If this list is empty, the only fees charged for a submit to this + * topic SHALL be the network and node fees.
    + * If this list is not empty, each fee defined in this set SHALL + * be evaluated for each message submitted to this topic, and the + * resultant total assessed fees SHALL be charged.
    + * If this list is not empty, custom fees defined here SHALL be + * charged _in addition to_ the base network and node fees. + */ + repeated FixedCustomFee custom_fees = 13; } diff --git a/sdk/src/main/proto/transaction.proto b/sdk/src/main/proto/transaction.proto index 494bff6bd..bb83a1f11 100644 --- a/sdk/src/main/proto/transaction.proto +++ b/sdk/src/main/proto/transaction.proto @@ -1,13 +1,22 @@ +/** + * # Transaction + * A (mostly legacy) wrapper around the bytes of a + * serialized `SignedTransaction` message. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,49 +28,614 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; -// <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; import "basic_types.proto"; -import "transaction_body.proto"; + +import "system_delete.proto"; +import "system_undelete.proto"; +import "freeze.proto"; + +import "contract_call.proto"; +import "contract_create.proto"; +import "contract_update.proto"; + +import "crypto_add_live_hash.proto"; +import "crypto_create.proto"; +import "crypto_delete.proto"; +import "crypto_delete_live_hash.proto"; +import "crypto_transfer.proto"; +import "crypto_update.proto"; +import "crypto_approve_allowance.proto"; +import "crypto_delete_allowance.proto"; + +import "ethereum_transaction.proto"; + +import "file_append.proto"; +import "file_create.proto"; +import "file_delete.proto"; +import "file_update.proto"; + +import "duration.proto"; +import "contract_delete.proto"; + +import "consensus_create_topic.proto"; +import "consensus_update_topic.proto"; +import "consensus_delete_topic.proto"; +import "consensus_submit_message.proto"; + +import "unchecked_submit.proto"; + +import "token_create.proto"; +import "token_freeze_account.proto"; +import "token_unfreeze_account.proto"; +import "token_grant_kyc.proto"; +import "token_revoke_kyc.proto"; +import "token_delete.proto"; +import "token_update.proto"; +import "token_mint.proto"; +import "token_burn.proto"; +import "token_wipe_account.proto"; +import "token_associate.proto"; +import "token_dissociate.proto"; +import "token_fee_schedule_update.proto"; +import "token_pause.proto"; +import "token_unpause.proto"; +import "token_update_nfts.proto"; +import "token_reject.proto"; +import "token_airdrop.proto"; +import "token_cancel_airdrop.proto"; +import "token_claim_airdrop.proto"; + +import "schedule_create.proto"; +import "schedule_delete.proto"; +import "schedule_sign.proto"; + +import "node_stake_update.proto"; +import "util_prng.proto"; + +import "node_create.proto"; +import "node_update.proto"; +import "node_delete.proto"; + +import "custom_fees.proto"; +import "state_signature_transaction.proto"; + +import "history_proof_signature.proto"; +import "history_proof_key_publication.proto"; +import "history_proof_vote.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. - * The SignatureList field is deprecated and succeeded by SignatureMap. + * A wrapper around signed transaction bytes.
    + * This was originally a transaction with body, signatures, and/or bytes, + * but is not only a wrapper around a byte array containing signed transction + * bytes. + * + * The `signedTransactionBytes` field is REQUIRED and MUST contain a valid, + * serialized, `SignedTransaction` message.
    + * All other fields are deprecated and MUST NOT be set. + * + * #### Additional Notes + * The four deprecated fields will be removed and reserved in a future release. */ message Transaction { + // <<>> This comment is special code for setting PBJ Compiler java package /** - * The body of the transaction, which needs to be signed + * Replaced with `signedTransactionBytes`.
    + * The body of the transaction. */ TransactionBody body = 1 [deprecated = true]; /** - * The signatures on the body, to authorize the transaction; deprecated and to be succeeded by - * SignatureMap field + * Replaced with `signedTransactionBytes`.
    + * The signatures on the body. */ SignatureList sigs = 2 [deprecated = true]; /** - * The signatures on the body with the new format, to authorize the transaction + * Replaced with `signedTransactionBytes`.
    + * The signatures on the body with a newer format. */ SignatureMap sigMap = 3 [deprecated = true]; /** - * TransactionBody serialized into bytes, which needs to be signed + * Replaced with `signedTransactionBytes`.
    + * TransactionBody serialized into bytes. */ bytes bodyBytes = 4 [deprecated = true]; /** - * SignedTransaction serialized into bytes + * A valid, serialized, `SignedTransaction` message. + *

    + * This field MUST be present. + * This field MUST NOT exceed the current network transaction size limit + * (currently 6144 bytes). */ bytes signedTransactionBytes = 5; } + +/** + * A transaction body. + * + * Every transaction is structured as a signed byte array. That byte array + * is a serialized `TransactionBody`. The transaction body contains the full + * content of the transaction, while the `SignedTransaction` includes a + * signature map for signatures authenticating that byte array, and that is + * serialized and transmitted wrapped in a `Transaction` message.
    + * The bulk of this message is a `oneof` block which offers the option for + * any one of the transaction messages for the network. + * This message also includes several additional fields to specify + * various parameters required to process a transaction. + */ +message TransactionBody { + // <<>> This comment is special code for setting PBJ Compiler java package + reserved 30, 61, 62, 63, 64, 66, 67, 68; + + reserved "tssMessage", "tssVote", "tssShareSignature", "tssEncryptionKey"; + + /** + * A transaction identifier.
    + * Each transaction is uniquely identified by its transaction + * identifier. + *

    + * Each transaction identifier MUST be unique.
    + * Multiple transactions MAY be submitted with the same transaction + * identifier, but all except the first SHALL be rejected as duplicate + * transactions.
    + * This identifier MUST specify a `payer` account to be charged + * all fees associated with the transaction.
    + * This identifier MUST specify a "valid start time".
    + * The "valid start time" MUST be strictly _earlier_ than the current + * network consensus time.
    + * The "valid start time" MUST NOT be more than the current network + * configuration value for `transaction.maxValidDuration` seconds + * before the current network consensus time.
    + * This identifier MUST NOT set the `scheduled` flag.
    + * This identifier MUST NOT set a nonce value. + */ + TransactionID transactionID = 1; + + /** + * A node account identifier. + *

    + * This MUST identify the account of the consensus node to which + * this transaction is submitted. + */ + AccountID nodeAccountID = 2; + + /** + * A maximum transaction fee, in tinybar. + *

    + * The network SHALL NOT charge a transaction fee that exceeds this + * amount.
    + * The network MAY charge up to this amount, and reject the transaction, + * if the amount offered is insufficient to cover the required fees.
    + * The network MAY charge a minimum fee equal to 80% of the amount offered + * if the amount offered is much larger than the required fees. + */ + uint64 transactionFee = 3; + + /** + * A maximum duration in which to execute this transaction. + *

    + * This transaction SHALL be rejected as expired if the valid start time, + * extended by this duration, is less than the current network consensus + * time when the transaction is submitted.
    + * This transaction SHALL be rejected with an invalid duration if this + * value is greater than the current network configuration value for + * `transaction.maxValidDuration`. + */ + Duration transactionValidDuration = 4; + + /** + * Records are always generated.
    + * Obsolete option to not generate a record. + *

    + * This flag SHALL be ignored. Every transaction SHALL generate a record, + * or block stream equivalent. + */ + bool generateRecord = 5 [deprecated = true]; + + /** + * A short description for this transaction. + *

    + * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. + */ + string memo = 6; + + // The fields here are ordered in strictly ascending field ordinal + // order due to limitations in PBJ. + oneof data { + /** + * Call a function defined on a smart contract. + */ + ContractCallTransactionBody contractCall = 7; + + /** + * Create a smart contract. + */ + ContractCreateTransactionBody contractCreateInstance = 8; + + /** + * Update a smart contract. + */ + ContractUpdateTransactionBody contractUpdateInstance = 9; + + /** + * An obsolete, and unsupported, operation to add a "live hash" to + * an account. + */ + CryptoAddLiveHashTransactionBody cryptoAddLiveHash = 10 [deprecated = true]; + + /** + * Create a new Hedera account. + */ + CryptoCreateTransactionBody cryptoCreateAccount = 11; + + /** + * Delete an Hedera account.
    + * This will mark the account as deleted, and transfer all remaining + * HBAR to a receiver account. + */ + CryptoDeleteTransactionBody cryptoDelete = 12; + + /** + * An obsolete, and unsupported, operation to remove a "live hash" from + * an account. + */ + CryptoDeleteLiveHashTransactionBody cryptoDeleteLiveHash = 13 [deprecated = true]; + + /** + * Transfer HBAR between accounts. + */ + CryptoTransferTransactionBody cryptoTransfer = 14; + + /** + * Modify an Hedera account. + */ + CryptoUpdateTransactionBody cryptoUpdateAccount = 15; + + /** + * Append data to the end of a file. + */ + FileAppendTransactionBody fileAppend = 16; + + /** + * Create a new file. + */ + FileCreateTransactionBody fileCreate = 17; + + /** + * Delete a file.
    + * This will remove the content of the file, and mark the file as + * deleted. + */ + FileDeleteTransactionBody fileDelete = 18; + + /** + * Modify a file.
    + * This may modify any metadata, and/or _replace_ the content. + */ + FileUpdateTransactionBody fileUpdate = 19; + + /** + * Delete a file as an Hedera administrative function.
    + * This is a privileged operation. + */ + SystemDeleteTransactionBody systemDelete = 20; + + /** + * Restore a file deleted via `systemDelete`.
    + * This is a privileged operation. + */ + SystemUndeleteTransactionBody systemUndelete = 21; + + /** + * Delete a smart contract and transfer remaining balance + * to a specified account. + */ + ContractDeleteTransactionBody contractDeleteInstance = 22; + + /** + * Freeze the network.
    + * This is actually several possible operations, and the caller + * should examine the "freeze service" for more detail.
    + * This is a privileged operation. + */ + FreezeTransactionBody freeze = 23; + + /** + * Create a topic. + */ + ConsensusCreateTopicTransactionBody consensusCreateTopic = 24; + + /** + * Update a topic. + */ + ConsensusUpdateTopicTransactionBody consensusUpdateTopic = 25; + + /** + * Delete a topic. + */ + ConsensusDeleteTopicTransactionBody consensusDeleteTopic = 26; + + /** + * Submit a message to a topic.
    + * A message may be "chunked", and submitted in parts, if the total + * message size exceeds the limit for a single transaction. + */ + ConsensusSubmitMessageTransactionBody consensusSubmitMessage = 27; + + /** + * Unsupported system transaction. + *

    + * This transaction MAY be implemented in testing networks, but + * SHALL NOT be enabled or supported in production environments.
    + * Clients MUST NOT call this method, and any such transaction SHALL + * be rejected.
    + * A network MAY choose to charge punitive fees for attempting to + * execute an `uncheckedSubmit`. + */ + UncheckedSubmitBody uncheckedSubmit = 28; + + /** + * Create a new Hedera token. + */ + TokenCreateTransactionBody tokenCreation = 29; + + /** + * Freeze an account with respect to a token.
    + * A frozen account cannot transact in that token until unfrozen. + */ + TokenFreezeAccountTransactionBody tokenFreeze = 31; + + /** + * Unfreeze an account with respect to a token. + */ + TokenUnfreezeAccountTransactionBody tokenUnfreeze = 32; + + /** + * Grant KYC to an account with respect to a token.
    + * KYC is generally a "know your customer" assertion that a + * responsible entity has sufficient information to positively + * identify the account holder to relevant authorities. + */ + TokenGrantKycTransactionBody tokenGrantKyc = 33; + + /** + * Revoke KYC from an account with respect to a token. + */ + TokenRevokeKycTransactionBody tokenRevokeKyc = 34; + + /** + * Delete an Hedera token.
    + * The token will be marked deleted. + */ + TokenDeleteTransactionBody tokenDeletion = 35; + + /** + * Update an Hedera token.
    + * Depending on what fields are to be modified, the signature + * requirements will vary. See `TokenUpdateTransactionBody` for + * further detail. + */ + TokenUpdateTransactionBody tokenUpdate = 36; + + /** + * Mint new tokens.
    + * All minted tokens will be delivered to the treasury account for + * the token type. The "mint key" for the token must sign this + * transaction. + */ + TokenMintTransactionBody tokenMint = 37; + + /** + * Burn tokens from the treasury account.
    + * The "burn key" for the token must sign this transaction. + */ + TokenBurnTransactionBody tokenBurn = 38; + + /** + * Wipe tokens from an account.
    + * This will remove a specified amount of fungible/common tokens or + * a specified list of non-fungible/unique serial numbered tokens + * of a given token type from an Hedera account. The removed tokens + * are _burned_ as if by a `tokenBurn` transaction.
    + * The "wipe key" for the token must sign this transaction. + */ + TokenWipeAccountTransactionBody tokenWipe = 39; + + /** + * Associate tokens to an account. + */ + TokenAssociateTransactionBody tokenAssociate = 40; + + /** + * Dissociate tokens from an account. + */ + TokenDissociateTransactionBody tokenDissociate = 41; + + /** + * Create a schedule.
    + * A schedule is a request to execute a specific transaction, included + * in the create body, in the future. The scheduled transaction may + * execute as soon as all signature requirements are met with the + * schedule create or a subsequent schedule sign transaction. + * A schedule may, alternatively, execute on expiration if + * long-term schedules are enabled and the schedule meets signature + * requirements at that time. + */ + ScheduleCreateTransactionBody scheduleCreate = 42; + + /** + * Delete a schedule.
    + * The schedule will be marked as deleted. + */ + ScheduleDeleteTransactionBody scheduleDelete = 43; + + /** + * Sign a schedule.
    + * Add one or more cryptographic keys to the list of keys that have + * signed a schedule, and which may serve to meet the signature + * requirements for the scheduled transaction. + */ + ScheduleSignTransactionBody scheduleSign = 44; + + /** + * Update the custom fee schedule for a token.
    + * This transaction must be signed by the "fee schedule key" + * for the token. + */ + TokenFeeScheduleUpdateTransactionBody token_fee_schedule_update = 45; + + /** + * Pause a Token. + *

    + * This transaction MUST be signed by the "pause key" for the token. + */ + TokenPauseTransactionBody token_pause = 46; + + /** + * Unpause a Token. + *

    + * This transaction MUST be signed by the "pause key" for the token. + */ + TokenUnpauseTransactionBody token_unpause = 47; + + /** + * Add one or more approved allowances for spenders to transfer the + * paying account's hbar or tokens. + */ + CryptoApproveAllowanceTransactionBody cryptoApproveAllowance = 48; + + /** + * Delete one or more approvals for spenders to transfer the + * paying account's hbar or tokens. + */ + CryptoDeleteAllowanceTransactionBody cryptoDeleteAllowance = 49; + + /** + * Perform an Ethereum encoded transaction. + */ + EthereumTransactionBody ethereumTransaction = 50; + + /** + * Update the staking information.
    + * This internal transaction is performed at the end of a staking + * period to complete staking calculations and indicate that new + * staking period has started. + */ + NodeStakeUpdateTransactionBody node_stake_update = 51; + + /** + * Provide a deterministic pseudorandom number based on network state. + */ + UtilPrngTransactionBody util_prng = 52; + + /** + * Update one or more non-fungible/unique tokens.
    + * This will update metadata for one or more serial numbers within + * a collection (token type). + */ + TokenUpdateNftsTransactionBody token_update_nfts = 53; + + /** + * Create a new node in the network address book.
    + * This is a privileged operation. + *

    + * This transaction SHALL create a new consensus node record and add + * that record to the network address book. + */ + com.hedera.hapi.node.addressbook.NodeCreateTransactionBody nodeCreate = 54; + + /** + * Update a node in the network address book.
    + * This is a privileged operation. + *

    + * This transaction SHALL update an existing consensus node record in + * the network address book. + */ + com.hedera.hapi.node.addressbook.NodeUpdateTransactionBody nodeUpdate = 55; + + /** + * Delete a node from the network address book.
    + * This is a privileged operation. + *

    + * This transaction SHALL mark an existing consensus node record as + * deleted and remove that node from the network address book. + */ + com.hedera.hapi.node.addressbook.NodeDeleteTransactionBody nodeDelete = 56; + + /** + * Reject and return a token to treasury.
    + * This transaction will transfer one or more tokens or token + * balances held by the requesting account to the treasury + * for each token type. + *

    + * Each transfer MUST be one of the following: + *

      + *
    • A single non-fungible/unique token.
      • + *
    • The full balance held for a fungible/common + * token type.
      • + *
    + * When complete, the requesting account SHALL NOT hold the + * rejected tokens.
    + * Custom fees and royalties defined for the tokens rejected + * SHALL NOT be charged for this transaction. + */ + TokenRejectTransactionBody tokenReject = 57; + + /** + * "Airdrop" tokens.
    + * This transaction sends tokens from one or more "sender" accounts + * to one or more "recipient" accounts. + *

    + * If a recipient account cannot immediately receive the token(s) sent, + * a "pending" airdrop SHALL be created and MUST be claimed. + */ + TokenAirdropTransactionBody tokenAirdrop = 58; + + /** + * Cancel one or more "pending" airdrops that are not yet claimed. + */ + TokenCancelAirdropTransactionBody tokenCancelAirdrop = 59; + + /** + * Claim one or more "pending" airdrops. + */ + TokenClaimAirdropTransactionBody tokenClaimAirdrop = 60; + + /** + * A transaction body for signature of a state root hash gossiped to other nodes + */ + com.hedera.hapi.platform.event.StateSignatureTransaction state_signature_transaction = 65; + + /** + * A transaction body for contributed a signature with a node's proof key to a history proof. + */ + com.hedera.hapi.services.auxiliary.history.HistoryProofSignatureTransactionBody history_proof_signature = 69; + + /** + * A transaction body for publishing a node's metadata proof key. + */ + com.hedera.hapi.services.auxiliary.history.HistoryProofKeyPublicationTransactionBody history_proof_key_publication = 70; + + /** + * A transaction body for voting on a metadata proof descending from the ledger id. + */ + com.hedera.hapi.services.auxiliary.history.HistoryProofVoteTransactionBody history_proof_vote = 71; + } + + /** + * A list of maximum custom fees that the users are willing to pay. + *

    + * This field is OPTIONAL.
    + * If left empty, the users are accepting to pay any custom fee.
    + * If used with a transaction type that does not support custom fee limits, the transaction will fail. + */ + repeated CustomFeeLimit max_custom_fees = 1001; +} diff --git a/sdk/src/main/proto/transaction_body.proto b/sdk/src/main/proto/transaction_body.proto deleted file mode 100644 index e27564d57..000000000 --- a/sdk/src/main/proto/transaction_body.proto +++ /dev/null @@ -1,441 +0,0 @@ -syntax = "proto3"; - -package proto; - -/* - * Copyright (C) 2024 Hedera Hashgraph, LLC - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -option java_package = "com.hedera.hashgraph.sdk.proto"; -// <<>> This comment is special code for setting PBJ Compiler java package -option java_multiple_files = true; - -import "system_delete.proto"; -import "system_undelete.proto"; -import "freeze.proto"; - -import "contract_call.proto"; -import "contract_create.proto"; -import "contract_update.proto"; - -import "crypto_add_live_hash.proto"; -import "crypto_create.proto"; -import "crypto_delete.proto"; -import "crypto_delete_live_hash.proto"; -import "crypto_transfer.proto"; -import "crypto_update.proto"; -import "crypto_approve_allowance.proto"; -import "crypto_delete_allowance.proto"; - -import "ethereum_transaction.proto"; - -import "file_append.proto"; -import "file_create.proto"; -import "file_delete.proto"; -import "file_update.proto"; - -import "duration.proto"; -import "basic_types.proto"; -import "contract_delete.proto"; - -import "consensus_create_topic.proto"; -import "consensus_update_topic.proto"; -import "consensus_delete_topic.proto"; -import "consensus_submit_message.proto"; - -import "unchecked_submit.proto"; - -import "token_create.proto"; -import "token_freeze_account.proto"; -import "token_unfreeze_account.proto"; -import "token_grant_kyc.proto"; -import "token_revoke_kyc.proto"; -import "token_delete.proto"; -import "token_update.proto"; -import "token_mint.proto"; -import "token_burn.proto"; -import "token_wipe_account.proto"; -import "token_associate.proto"; -import "token_dissociate.proto"; -import "token_fee_schedule_update.proto"; -import "token_pause.proto"; -import "token_unpause.proto"; -import "token_update_nfts.proto"; -import "token_reject.proto"; -import "token_airdrop.proto"; -import "token_cancel_airdrop.proto"; -import "token_claim_airdrop.proto"; - -import "schedule_create.proto"; -import "schedule_delete.proto"; -import "schedule_sign.proto"; - -import "node_stake_update.proto"; -import "util_prng.proto"; - -import "node_create.proto"; -import "node_update.proto"; -import "node_delete.proto"; - -import "tss_message.proto"; -import "tss_vote.proto"; -import "tss_share_signature.proto"; - -/** - * A single transaction. All transaction types are possible here. - */ -message TransactionBody { - /** - * 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; - - /** - * The choices here are arranged by service in roughly lexicographical order. The field ordinals are non-sequential, and a result of the historical order of implementation. - */ - oneof data { - /** - * Calls a function of a contract instance - */ - ContractCallTransactionBody contractCall = 7; - - /** - * Creates a contract instance - */ - ContractCreateTransactionBody contractCreateInstance = 8; - - /** - * Updates a contract - */ - ContractUpdateTransactionBody contractUpdateInstance = 9; - - /** - * 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; - - /** - * Delete contract and transfer remaining balance into specified account - */ - ContractDeleteTransactionBody contractDeleteInstance = 22; - - /** - * 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; - - /** - * 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; - - /** - * 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; - - /** - * Updates a token's custom fee schedule - */ - TokenFeeScheduleUpdateTransactionBody token_fee_schedule_update = 45; - - /** - * Pauses the Token - */ - TokenPauseTransactionBody token_pause = 46; - - /** - * Unpauses the Token - */ - TokenUnpauseTransactionBody token_unpause = 47; - - /** - * Adds one or more approved allowances for spenders to transfer the paying account's hbar or tokens. - */ - CryptoApproveAllowanceTransactionBody cryptoApproveAllowance = 48; - - /** - * Deletes one or more of the specific approved NFT serial numbers on an owner account. - */ - CryptoDeleteAllowanceTransactionBody cryptoDeleteAllowance = 49; - - /** - * An Ethereum encoded transaction. - */ - EthereumTransactionBody ethereumTransaction = 50; - - /** - * Updates the staking info at the end of staking period to indicate new staking period has started. - */ - NodeStakeUpdateTransactionBody node_stake_update = 51; - - /** - * Generates a pseudorandom number. - */ - UtilPrngTransactionBody util_prng = 52; - - /** - * Update the metadata of one or more NFT's of a specific token type. - */ - TokenUpdateNftsTransactionBody token_update_nfts = 53; - - /** - * A transaction body for a `createNode` request. - *

    - * This transaction SHALL create a new consensus node record and add - * that record to the network address book. - */ - com.hedera.hashgraph.hapi.node.addressbook.NodeCreateTransactionBody nodeCreate = 54; - - /** - * A transaction body for an `updateNode` request. - *

    - * This transaction SHALL update an existing consensus node record in - * the network address book. - */ - com.hedera.hashgraph.hapi.node.addressbook.NodeUpdateTransactionBody nodeUpdate = 55; - - /** - * A transaction body for a `deleteNode` request. - *

    - * This transaction SHALL remove an existing consensus node record from - * the network address book. - */ - com.hedera.hashgraph.hapi.node.addressbook.NodeDeleteTransactionBody nodeDelete = 56; - - /** - * A transaction body to "reject" undesired tokens.
    - * This transaction will transfer one or more tokens or token - * balances held by the requesting account to the treasury - * for each token type. - *

    - * Each transfer MUST be one of the following: - *

      - *
    • A single non-fungible/unique token.
      • - *
    • The full balance held for a fungible/common - * token type.
      • - *
    - * When complete, the requesting account SHALL NOT hold the - * rejected tokens.
    - * Custom fees and royalties defined for the tokens rejected - * SHALL NOT be charged for this transaction. - */ - TokenRejectTransactionBody tokenReject = 57; - - /** - * A transaction body for a `tokenAirdrop` request. - */ - TokenAirdropTransactionBody tokenAirdrop = 58; - - /** - * A transaction body for a `cancelAirdrop` request. - */ - TokenCancelAirdropTransactionBody tokenCancelAirdrop = 59; - - /** - * A transaction body for a `claimAirdrop` request. - */ - TokenClaimAirdropTransactionBody tokenClaimAirdrop = 60; - - /** - * A transaction body for a `tssMessage` request. - */ - com.hedera.hashgraph.hapi.services.auxiliary.tss.TssMessageTransactionBody tssMessage = 61; - - /** - * A transaction body for a `tssVote` request. - */ - com.hedera.hashgraph.hapi.services.auxiliary.tss.TssVoteTransactionBody tssVote = 62; - - /** - * A transaction body for a 'tssShareSignature` request - */ - com.hedera.hashgraph.hapi.services.auxiliary.tss.TssShareSignatureTransactionBody tssShareSignature = 63; - } -} diff --git a/sdk/src/main/proto/transaction_contents.proto b/sdk/src/main/proto/transaction_contents.proto index 01f291221..9605db204 100644 --- a/sdk/src/main/proto/transaction_contents.proto +++ b/sdk/src/main/proto/transaction_contents.proto @@ -1,13 +1,23 @@ +/** + * # Transaction Contents + * The Signed Transaction message which forms the content of a transaction + * `signedTransactionBytes`. This message is the result of several changes + * to transaction message structure over time. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +29,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -28,14 +37,29 @@ option java_multiple_files = true; import "basic_types.proto"; +/** + * A combination transaction bytes and a map of signatures.
    + * This message contains a serialized `TransactionBody` in a byte array + * and a `SignatureMap` that contains all of the signatures offered to + * authenticate the transaction. + * + * ### Block Stream Effects + * This content is recorded in the record stream exactly as received. + */ message SignedTransaction { /** - * TransactionBody serialized into bytes, which needs to be signed + * A byte array containing a serialized `TransactionBody`. + *

    + * This content is what the signatures in `sigMap` MUST sign. */ bytes bodyBytes = 1; /** - * The signatures on the body with the new format, to authorize the transaction + * A set of cryptographic signatures. + *

    + * This set MUST contain all signatures required to authenticate + * and authorize the transaction.
    + * This set MAY contain additional signatures. */ SignatureMap sigMap = 2; } diff --git a/sdk/src/main/proto/transaction_get_fast_record.proto b/sdk/src/main/proto/transaction_get_fast_record.proto index 49c0e49f8..a37d440c9 100644 --- a/sdk/src/main/proto/transaction_get_fast_record.proto +++ b/sdk/src/main/proto/transaction_get_fast_record.proto @@ -1,13 +1,30 @@ +/** + * # Get Fast Record + * Get a recent transaction record "fast". + * + * > Important + * >> This query is obsolete and not supported.
    + * >> Any query of this type that is submitted SHALL fail with a `PRE_CHECK` + * >> result of `NOT_SUPPORTED`. + * + * > Implementation Note + * >> This query is _defined_ for "Crypto" service, but is _implemented_ by + * >> the "Network Admin" service. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +36,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,15 +48,20 @@ 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 { + option deprecated = true; /** - * 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 information sent with every query operation.
    + * This includes the signed payment and what kind of response is requested + * (cost, state proof, both, or neither). */ QueryHeader header = 1; @@ -51,16 +72,19 @@ message TransactionGetFastRecordQuery { } /** - * 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 { + option deprecated = true; /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
    + * This includes the values requested in the `QueryHeader` + * (cost, state proof, both, or neither). */ ResponseHeader header = 1; diff --git a/sdk/src/main/proto/transaction_get_receipt.proto b/sdk/src/main/proto/transaction_get_receipt.proto index 4044b6c58..cac0c0d88 100644 --- a/sdk/src/main/proto/transaction_get_receipt.proto +++ b/sdk/src/main/proto/transaction_get_receipt.proto @@ -1,13 +1,34 @@ +/** + * # Get Transaction Receipt + * This query is central to client interactions. A client must query + * the network for the "receipt" after a transaction is submitted to know + * whether the transaction succeeded and the consensus result. + * + * > Implementation Note + * >> This query is _defined_ for "Crypto" service, but is _implemented_ by + * >> the "Network Admin" service. + * + * > Note + * >> The mechanism for transaction receipts and results is subject to + * >> considerable change in the near future. Clients heavily dependent + * >> on direct network queries for transaction receipts may consider + * >> changes needed to query a mirror node for transaction receipts + * >> and results instead. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +40,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,70 +52,148 @@ 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 + * A query to retrieve a transaction receipt. + * This query retrieves the post-consensus (final) result of a transaction. + * A transaction receipt may not be available if queried too early + * (less than 5-10 seconds), or too late (more than 3 minutes). If a receipt + * is available, it contains basic transaction results. A query to a mirror + * node (or other archival system) is required to obtain full detail for a + * transaction, or any result after the basic receipt time period. + * + * This query is "free". The payment field in the header MUST be empty.
    + * If a receipt is not available, the response SHALL be `UNKNOWN`.
    + * A transaction receipt SHALL be available after the network reaches + * consensus for a transaction.
    + * A transaction receipt SHALL NOT be available after the end of the network + * configured "receipt period", typically three(3) minutes. + * + *

    + *
    What is the "first" transaction?
    + *
    The "first" transaction SHALL be the the transaction with + * the earliest consensus time and a status that is neither + * `INVALID_NODE_ACCOUNT` nor `INVALID_PAYER_SIGNATURE`.
    + * If no transaction is found meeting this status criteria, the + * "first" transaction SHALL be the transaction with the earliest + * consensus time.
    + *
    What is a "child" transaction?
    + *
    A "child" transaction is any transaction created in the process of + * completing another transaction. These are most common with a smart + * contract call, where a call to a contract may initiate one or more + * additional transactions to complete a complex process.
    + *
    */ message TransactionGetReceiptQuery { /** - * 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 information sent with every query operation.
    + * This includes 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. + * A transaction identifier. + *

    + * This MUST contain the full identifier, as submitted, for the + * transaction to query. */ 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. + * A flag to request duplicates. + *

    + * If set, every transaction receipt within the receipt period that + * matches the requested transaction identifier SHALL be returned.
    + * If not set, duplicate transactions SHALL NOT be returned.
    + * If not set, only the receipt for the first matching transaction to + * reach consensus SHALL be returned. */ bool includeDuplicates = 3; /** - * Whether the response should include the receipts of any child transactions spawned by the - * top-level transaction with the given transactionID. + * A flag to request "child" receipts. + *

    + * If set, the response SHALL include receipts for each child transaction + * executed as part of the requested parent transaction.
    + * If not set, the response SHALL NOT include any receipts for child + * transactions. */ bool include_child_receipts = 4; } /** - * 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 message for a `getTransactionReceipts` query. + * + * The `receipt` field SHALL return the receipt for the "first" transaction + * that matches the transaction identifier requested.
    + * If receipts for duplicate transactions are requested, those duplicate + * receipts SHALL be present in the `duplicateTransactionReceipts` list.
    + * If receipts for child transactions are requested, those child receipts + * SHALL be present in the `child_transaction_receipts` list.
    + * A state proof SHALL NOT be provided for this response; transaction receipts + * are not retained in network state. + * + *

    + *
    What is the "first" transaction?
    + *
    The "first" transaction receipt SHALL be the receipt for the + * first transaction with status that is neither + * `INVALID_NODE_ACCOUNT` nor `INVALID_PAYER_SIGNATURE`.
    + * If no transaction is found meeting the status criteria, the + * "first" transaction SHALL be the first transaction by + * consensus time.
    + *
    What is a "child" transaction?
    + *
    A "child" transaction is any transaction created in the process of + * completing another transaction. These are most common with a smart + * contract call, where a call to a contract may initiate one or more + * additional transactions to complete a complex process.
    + *
    */ message TransactionGetReceiptResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither + * The standard response information for queries.
    + * This includes the values requested in the `QueryHeader` + * (cost, state proof, 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. + * A transaction receipt. + *

    + * This SHALL be the receipt for the "first" transaction that matches + * the transaction identifier requested.
    + * If the identified transaction has not reached consensus, this receipt + * SHALL have a `status` of `UNKNOWN`.
    + * If the identified transaction reached consensus prior to the current + * configured receipt period (typically the last 180 seconds), this receipt + * SHALL have a `status` of `UNKNOWN`. */ TransactionReceipt receipt = 2; /** - * The receipts of processing all transactions with the given id, in consensus time order. + * A list of duplicate transaction receipts. + *

    + * If the request set the `includeDuplicates` flat, this list SHALL + * include the receipts for each duplicate transaction associated to the + * requested transaction identifier. + * If the request did not set the `includeDuplicates` flag, this list + * SHALL be empty.
    + * If the `receipt` status is `UNKNOWN`, this list SHALL be empty.
    + * This list SHALL be in order by consensus timestamp. */ repeated TransactionReceipt duplicateTransactionReceipts = 4; /** - * The receipts (if any) of all child transactions spawned by the transaction with the - * given top-level id, in consensus order. Always empty if the top-level status is UNKNOWN. + * A list of receipts for all child transactions spawned by the requested + * transaction. + *

    + * If the request set the `include_child_receipts` flag, this list SHALL + * include receipts for each child transaction executed as part of the + * requested parent transaction.
    + * If the request did not set the `include_child_receipts` flag, this + * list SHALL be empty.
    + * If the parent transaction did not initiate any child transactions + * this list SHALL be empty.
    + * If the `receipt` status is `UNKNOWN`, this list SHALL be empty.
    + * This list SHALL be in order by consensus timestamp. */ repeated TransactionReceipt child_transaction_receipts = 5; } diff --git a/sdk/src/main/proto/transaction_get_record.proto b/sdk/src/main/proto/transaction_get_record.proto index 88cc0477f..d71f25e60 100644 --- a/sdk/src/main/proto/transaction_get_record.proto +++ b/sdk/src/main/proto/transaction_get_record.proto @@ -1,13 +1,33 @@ +/** + * # Get Transaction Record + * Messages for a query to obtain a transaction record. This particular + * query is used by `getTxRecordByTxID` in the "Crypto" service API. + * + * > Note + * >> Much more detailed information for transaction records is available + * >> from a mirror node, and the mirror node retains transaction records + * >> long term, rather than for a short "cache" duration. Clients may + * >> prefer the mirror node graph API to query transaction records, rather + * >> than this query. + * + * > Implementation Note + * >> This query is _defined_ for "Crypto" service, but is _implemented_ by + * >> the "Network Admin" service. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +39,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -32,70 +51,143 @@ 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. + * Request for a `TransactionGetRecord` (a.k.a. `getTxRecordByTxID`) query. + *

    + * A transaction record SHALL be available after the network reaches + * consensus and completes execution for a transaction.
    + * A transaction record SHALL NOT be available after the end of the network + * configured "record cache duration". + * + *

    + *
    What is the "first" transaction?
    + *
    The "first" transaction SHALL be the the transaction with + * the earliest consensus time and a status that is neither + * `INVALID_NODE_ACCOUNT` nor `INVALID_PAYER_SIGNATURE`.
    + * If no transaction is found meeting this status criteria, the + * "first" transaction SHALL be the transaction with the earliest + * consensus time.
    + *
    What is a "child" transaction?
    + *
    A "child" transaction is any transaction created in the process of + * completing another transaction. These are most common with a smart + * contract call, where a call to a contract may initiate one or more + * additional transactions to complete a complex process.
    + *
    */ message TransactionGetRecordQuery { /** - * 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 information sent with every query operation.
    + * This includes 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. + * A transaction identifier. + *

    + * This MUST contain the full identifier, as submitted, for the + * transaction to query. */ 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.. + * A flag to request duplicates. + *

    + * If set, every transaction record within the record cache duration that + * matches the requested transaction identifier SHALL be returned.
    + * If not set, duplicate transactions SHALL NOT be returned.
    + * If not set, only the record for the first matching transaction to + * reach consensus SHALL be returned. */ bool includeDuplicates = 3; /** - * Whether the response should include the records of any child transactions spawned by the - * top-level transaction with the given transactionID. + * A flag to request "child" records. + *

    + * If set, the response SHALL include records for each child transaction + * executed as part of the requested parent transaction.
    + * If not set, the response SHALL NOT include any records for child + * transactions. */ bool include_child_records = 4; } /** - * Response when the client sends the node TransactionGetRecordQuery + * Response message for a `getTxRecordByTxID` query. + * + * The `transactionRecord` field SHALL return the record for the "first" + * transaction that matches the transaction identifier requested.
    + * If records for duplicate transactions are requested, those duplicate + * records SHALL be present in the `duplicateTransactionReceipts` list.
    + * If records for child transactions are requested, those child records SHALL + * be present in the `child_transaction_records` list.
    + * A state proof MAY be provided for this response; provided the record is + * still available from the consensus nodes. + * + *

    + *
    What is the "first" transaction?
    + *
    The "first" transaction receipt SHALL be the receipt for the + * first transaction with status that is neither + * `INVALID_NODE_ACCOUNT` nor `INVALID_PAYER_SIGNATURE`.
    + * If no transaction is found meeting the status criteria, the + * "first" transaction SHALL be the first transaction by + * consensus time.
    + *
    What is a "child" transaction?
    + *
    A "child" transaction is any transaction created in the process of + * completing another transaction. These are most common with a smart + * contract call, where a call to a contract may initiate one or more + * additional transactions to complete a complex process.
    + *
    + * */ message TransactionGetRecordResponse { /** - * Standard response from node to client, including the requested fields: cost, or state proof, - * or both, or neither. + * The standard response information for queries.
    + * This includes the values requested in the `QueryHeader` + * (cost, state proof, 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. + * A transaction record. + *

    + * This SHALL be the record for the "first" transaction that matches + * the transaction identifier requested.
    + * If the identified transaction has not reached consensus, this + * record SHALL have a `status` of `UNKNOWN`.
    + * If the identified transaction reached consensus prior to the + * current configured record cache duration, this record SHALL + * have a `status` of `UNKNOWN`. */ TransactionRecord transactionRecord = 3; /** - * The records of processing all consensus transaction with the same id as the distinguished - * record above, in chronological order. + * A list of duplicate transaction records. + *

    + * If the request set the `includeDuplicates` flat, this list SHALL + * include the records for each duplicate transaction associated to the + * requested transaction identifier. + * If the request did not set the `includeDuplicates` flag, this list + * SHALL be empty.
    + * If the `transactionRecord` status is `UNKNOWN`, this list + * SHALL be empty.
    + * This list SHALL be in order by consensus timestamp. */ repeated TransactionRecord duplicateTransactionRecords = 4; /** - * The records of processing all child transaction spawned by the transaction with the given - * top-level id, in consensus order. Always empty if the top-level status is UNKNOWN. + * A list of records for all child transactions spawned by the requested + * transaction. + *

    + * If the request set the `include_child_records` flag, this list SHALL + * include records for each child transaction executed as part of the + * requested parent transaction.
    + * If the request did not set the `include_child_records` flag, this + * list SHALL be empty.
    + * If the parent transaction did not initiate any child transactions + * this list SHALL be empty.
    + * If the `transactionRecord` status is `UNKNOWN`, this list + * SHALL be empty.
    + * This list SHALL be in order by consensus timestamp. */ repeated TransactionRecord child_transaction_records = 5; } - diff --git a/sdk/src/main/proto/transaction_receipt.proto b/sdk/src/main/proto/transaction_receipt.proto index 156ec6434..93de7d5d6 100644 --- a/sdk/src/main/proto/transaction_receipt.proto +++ b/sdk/src/main/proto/transaction_receipt.proto @@ -1,3 +1,15 @@ +/** + * # Transaction Receipt + * The receipt returned when the results of a transaction are requested via + * `TransactionGetReceiptQuery`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; @@ -27,143 +39,165 @@ 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. + * + * Most items in this object are only set for specific transactions. + * Those values SHALL be unset for all other transactions. */ 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. + *

    + * This SHALL be `UNKNOWN` if consensus has not been reached.
    + * This SHALL be `UNKNOWN` 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 for 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 SHA-384 digest with input data determined by the - * value of the `topicRunningHashVersion` field.
    + * In the receipt of a `ConsensusSubmitMessage`, the new running hash of + * the topic that received the message.
    + *

    + * The inputs to the topic running hash have changed over time.
    + * This 48-byte field is the output of a SHA-384 digest with input data + * determined by the value of the `topicRunningHashVersion` field.
    * All new transactions SHALL use `topicRunningHashVersion` `3`.
    - * The bytes of each uint64 or uint32 encoded for the hash input MUST be in Big-Endian format. + * The bytes of each uint64 or uint32 encoded for the hash input MUST be + * in Big-Endian format. *

    - *

    - * If the `topicRunningHashVersion` is '0' or '1', then the input data to the SHA-384 digest are, - * in order: + *
    + *

    + * The most recent version is denoted by `topicRunningHashVersion = 3`. + *

    + * This version SHALL include, in order *

      - *
    1. The previous running hash of the topic (48 bytes)
      2. - *
    2. The topic's shard (8 bytes)
      3. - *
    3. The topic's realm (8 bytes)
      4. - *
    4. The topic's number (8 bytes)
      5. - *
    5. The number of seconds since the epoch when the `ConsensusSubmitMessage` reached - * consensus (8 bytes)
      6. - *
    6. The number of nanoseconds within the second when the `ConsensusSubmitMessage` reached - * consensus (4 bytes)
      7. - *
    7. The `topicSequenceNumber` (8 bytes)
      8. - *
    8. The message bytes from the `ConsensusSubmitMessage` (variable).
      9. + *
    9. The previous running hash of the topic (48 bytes)
      10. + *
    10. The `topic_running_hash_version` field (8 bytes)
      11. + *
    11. The payer account's shard (8 bytes)
      12. + *
    12. The payer account's realm (8 bytes)
      13. + *
    13. The payer account's number (8 bytes)
      14. + *
    14. The topic's shard (8 bytes)
      15. + *
    15. The topic's realm (8 bytes)
      16. + *
    16. The topic's number (8 bytes)
      17. + *
    17. The number of seconds since the epoch when the + * `ConsensusSubmitMessage` reached consensus (8 bytes)
      18. + *
    18. The number of nanoseconds within the second when the + * `ConsensusSubmitMessage` reached consensus (4 bytes)
      19. + *
    19. The `topic_sequence_number` field (8 bytes)
      20. + *
    20. The output of a SHA-384 digest of the message bytes from the + * `ConsensusSubmitMessage` (48 bytes)
      21. *
    - *
    - * If the `topicRunningHashVersion` is '2', then the input data to the SHA-384 digest are, in - * order: + *
    + *

    + * The next older version is denoted by `topicRunningHashVersion = 2`. + *

    + * This version SHALL include, in order *

      - *
    1. The previous running hash of the topic (48 bytes)
      2. - *
    2. The `topicRunningHashVersion` (8 bytes)
      3. - *
    3. The topic's shard (8 bytes)
      4. - *
    4. The topic's realm (8 bytes)
      5. - *
    5. The topic's number (8 bytes)
      6. - *
    6. The number of seconds since the epoch when the `ConsensusSubmitMessage` reached - * consensus (8 bytes)
      7. - *
    7. The number of nanoseconds within the second when the `ConsensusSubmitMessage` reached - * consensus (4 bytes)
      8. - *
    8. The `topicSequenceNumber` (8 bytes)
      9. - *
    9. The output of a SHA-384 digest of the message bytes from the `ConsensusSubmitMessage` - * (48 bytes)
      10. + *
    10. The previous running hash of the topic (48 bytes)
      11. + *
    11. The `topic_running_hash_version` field (8 bytes)
      12. + *
    12. The topic's shard (8 bytes)
      13. + *
    13. The topic's realm (8 bytes)
      14. + *
    14. The topic's number (8 bytes)
      15. + *
    15. The number of seconds since the epoch when the + * `ConsensusSubmitMessage` reached consensus (8 bytes)
      16. + *
    16. The number of nanoseconds within the second when the + * `ConsensusSubmitMessage` reached consensus (4 bytes)
      17. + *
    17. The `topic_sequence_number` field (8 bytes)
      18. + *
    18. The output of a SHA-384 digest of the message bytes from the + * `ConsensusSubmitMessage` (48 bytes)
      19. *
    - *
    - * If the `topicRunningHashVersion` is '3', then the input data to the SHA-384 digest - * are, in order: + *
    + *

    + * The original version, used at genesis, is denoted + * by `topicRunningHashVersion = 1` or `topicRunningHashVersion = 0`. + *

    + * This version SHALL include, in order *

      - *
    1. The previous running hash of the topic (48 bytes)
      2. - *
    2. The `topicRunningHashVersion` (8 bytes)
      3. - *
    3. The payer account's shard (8 bytes)
      4. - *
    4. The payer account's realm (8 bytes)
      5. - *
    5. The payer account's number (8 bytes)
      6. - *
    6. The topic's shard (8 bytes)
      7. - *
    7. The topic's realm (8 bytes)
      8. - *
    8. The topic's number (8 bytes)
      9. - *
    9. The number of seconds since the epoch when the `ConsensusSubmitMessage` reached - * consensus (8 bytes)
      10. - *
    10. The number of nanoseconds within the second when the `ConsensusSubmitMessage` reached - * consensus (4 bytes)
      11. - *
    11. The `topicSequenceNumber` (8 bytes)
      12. - *
    12. The output of a SHA-384 digest of the message bytes from the `ConsensusSubmitMessage` - * (48 bytes)
      13. + *
    13. The previous running hash of the topic (48 bytes)
      14. + *
    14. The topic's shard (8 bytes)
      15. + *
    15. The topic's realm (8 bytes)
      16. + *
    16. The topic's number (8 bytes)
      17. + *
    17. The number of seconds since the epoch when the + * `ConsensusSubmitMessage` reached consensus (8 bytes)
      18. + *
    18. The number of nanoseconds within the second when the + * `ConsensusSubmitMessage` reached consensus (4 bytes)
      19. + *
    19. The `topic_sequence_number` field (8 bytes)
      20. + *
    20. The message bytes from the `ConsensusSubmitMessage` + * (variable)
      21. *
    */ 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 inputs 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`, or `TokenBurn`.
    + * For non-unique tokens, the current total supply of that token.
    + * For unique tokens,the total number of NFTs issued for that token. */ 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 enables the + * scheduled transaction to execute immediately, the `TransactionID` that + * should be used to query for the receipt or record of the scheduled + * transaction that was executed. */ 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 non-fungible/unique tokens, + * the serial numbers of the newly created tokens. */ repeated int64 serialNumbers = 14; diff --git a/sdk/src/main/proto/transaction_record.proto b/sdk/src/main/proto/transaction_record.proto index e3f121cc1..343019721 100644 --- a/sdk/src/main/proto/transaction_record.proto +++ b/sdk/src/main/proto/transaction_record.proto @@ -1,13 +1,26 @@ +/** + * # Transaction Record + * The record of a single transaction, including receipt and transaction + * results such as transfer lists, entropy, contract call result, etc...
    + * The record also includes fees, consensus time, EVM information, and + * other result metadata.
    + * Only values appropriate to the requested transaction are populated, all + * other fields will not be set (i.e. null or default values). + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +32,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -30,139 +42,185 @@ import "timestamp.proto"; import "basic_types.proto"; import "custom_fees.proto"; import "transaction_receipt.proto"; -import "crypto_transfer.proto"; -import "contract_call_local.proto"; +import "contract_types.proto"; /** * Response when the client sends the node TransactionGetRecordResponse */ message TransactionRecord { /** - * The status (reach consensus, or failed, or is unknown) and the ID of any new - * account/file/instance created. + * A transaction receipt. + *

    + * This SHALL report consensus status (reach consensus, failed, + * unknown) and the ID of any new entity (i.e. account, file, + * contract, schedule, etc...) created. */ TransactionReceipt receipt = 1; /** - * The hash of the Transaction that executed (not the hash of any Transaction that failed for - * having a duplicate TransactionID) + * A transaction hash value. + *

    + * This SHALL be the hash of the Transaction that executed and + * SHALL NOT be 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) + * A consensus timestamp. + *

    + * This SHALL be null if the transaction did not reach consensus yet. */ Timestamp consensusTimestamp = 3; /** - * The ID of the transaction this record represents + * A transaction identifier to the transaction associated to this record. */ TransactionID transactionID = 4; /** - * The memo that was submitted as part of the transaction (max 100 bytes) + * A transaction memo.
    + * This is the memo that was submitted as part of the transaction. + *

    + * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes` + * (default 100) bytes when encoded as UTF-8. */ string memo = 5; /** - * The actual transaction fee charged, not the original transactionFee value from - * TransactionBody + * A transaction fee charged. + *

    + * This SHALL be the actual transaction fee charged.
    + * This MAY NOT match the original `transactionFee` value + * from the `TransactionBody`. */ uint64 transactionFee = 6; oneof body { /** - * Record of the value returned by the smart contract function (if it completed and didn't - * fail) from ContractCallTransaction + * A contract call result.
    + * A record of the value returned by the smart contract function (if + * it completed and didn't fail) from a `ContractCallTransaction`. */ ContractFunctionResult contractCallResult = 7; /** - * Record of the value returned by the smart contract constructor (if it completed and - * didn't fail) from ContractCreateTransaction + * A contract creation result.
    + * A record of the value returned by the smart contract constructor (if + * it completed and didn't fail) from a `ContractCreateTransaction`. */ ContractFunctionResult contractCreateResult = 8; } /** - * 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. + * A transfer list for this transaction.
    + * This is a list of all HBAR transfers completed for this transaction. + *

    + * This MAY include fees, transfers performed by the transaction, + * transfers initiated by a smart contract it calls, or the creation + * of threshold records that it triggers. */ TransferList transferList = 10; /** - * All Token transfers as a result of this transaction + * A token transfer list for this transaction.
    + * This is a list of all non-HBAR token transfers + * completed for this transaction.
    */ repeated TokenTransferList tokenTransferLists = 11; /** - * Reference to the scheduled transaction ID that this transaction record represent + * A schedule reference.
    + * The reference to a schedule ID for the schedule that initiated this + * transaction, if this this transaction record represents a scheduled + * transaction. */ ScheduleID scheduleRef = 12; /** - * All custom fees that were assessed during a CryptoTransfer, and must be paid if the - * transaction status resolved to SUCCESS + * A list of all custom fees that were assessed during a CryptoTransfer. + *

    + * These SHALL be paid if the transaction status resolved to SUCCESS. */ repeated AssessedCustomFee assessed_custom_fees = 13; /** - * All token associations implicitly created while handling this transaction + * A list of all token associations implicitly or automatically + * created while handling this transaction. */ repeated TokenAssociation automatic_token_associations = 14; /** - * In the record of an internal transaction, the consensus timestamp of the user - * transaction that spawned it. + * A consensus timestamp for a child record. + *

    + * This SHALL be the consensus timestamp of a user transaction that + * spawned an internal child transaction. */ Timestamp parent_consensus_timestamp = 15; /** - * In the record of a CryptoCreate transaction triggered by a user transaction with a - * (previously unused) alias, the new account's alias. + * A new account alias.
    + *

    + * This is the new alias assigned to an account created as part + * of a CryptoCreate transaction triggered by a user transaction + * with a (previously unused) alias. */ - bytes alias = 16; + bytes alias = 16; /** - * The keccak256 hash of the ethereumData. This field will only be populated for - * EthereumTransaction. + * A keccak256 hash of the ethereumData. + *

    + * This field SHALL only be populated for EthereumTransaction. */ bytes ethereum_hash = 17; /** - * List of accounts with the corresponding staking rewards paid as a result of a transaction. + * A list of staking rewards paid. + *

    + * This SHALL be a list accounts with the corresponding staking + * rewards paid as a result of this transaction. */ repeated AccountAmount paid_staking_rewards = 18; oneof entropy { /** - * In the record of a UtilPrng transaction with no output range, a pseudorandom 384-bit string. + * A pseudorandom 384-bit sequence. + *

    + * This SHALL be returned in the record of a UtilPrng transaction + * with no output range, */ bytes prng_bytes = 19; /** - * In the record of a PRNG transaction with an output range, the output of a PRNG whose input was a 384-bit string. + * A pseudorandom 32-bit integer.
    + *

    + * This SHALL be returned in the record of a PRNG transaction with + * an output range specified. */ int32 prng_number = 20; } /** - * The new default EVM address of the account created by this transaction. - * This field is populated only when the EVM address is not specified in the related transaction body. + * A new default EVM address for an account created by + * this transaction. + *

    + * This field SHALL be populated only when the EVM address is not + * specified in the related transaction body. */ bytes evm_address = 21; /** * A list of pending token airdrops. - * Each pending airdrop represents a single requested transfer from a - * sending account to a recipient account. These pending transfers are - * issued unilaterally by the sending account, and MUST be claimed by the - * recipient account before the transfer MAY complete. - * A sender MAY cancel a pending airdrop before it is claimed. - * An airdrop transaction SHALL emit a pending airdrop when the recipient has no - * available automatic association slots available or when the recipient - * has set `receiver_sig_required`. + *

    + * Each pending airdrop SHALL represent a single requested transfer + * from a sending account to a recipient account.
    + * These pending transfers are issued unilaterally by the sending + * account, and MUST be claimed by the recipient account before + * the transfer SHALL complete.
    + * A sender MAY cancel a pending airdrop before it is claimed.
    + * An airdrop transaction SHALL emit a pending airdrop when the + * recipient has no available automatic association slots available + * or when the recipient has set `receiver_sig_required`. */ repeated PendingAirdropRecord new_pending_airdrops = 22; } @@ -173,16 +231,18 @@ message TransactionRecord { message PendingAirdropRecord { /** * A unique, composite, identifier for a pending airdrop. + *

    * This field is REQUIRED. */ PendingAirdropId pending_airdrop_id = 1; /** * A single pending airdrop amount. - * If the pending airdrop is for a fungible/common token this field is REQUIRED - * and SHALL be the current amount of tokens offered. - * If the pending airdrop is for a non-fungible/unique token, this field SHALL NOT - * be set. + *

    + * If the pending airdrop is for a fungible/common token this field + * is REQUIRED and SHALL be the current amount of tokens offered.
    + * If the pending airdrop is for a non-fungible/unique token, + * this field SHALL NOT be set. */ PendingAirdropValue pending_airdrop_value = 2; } diff --git a/sdk/src/main/proto/transaction_response.proto b/sdk/src/main/proto/transaction_response.proto index 94b98db13..956631da9 100644 --- a/sdk/src/main/proto/transaction_response.proto +++ b/sdk/src/main/proto/transaction_response.proto @@ -1,13 +1,25 @@ +/** + * # Transaction Response + * Message(s) sent in response to submitting a transaction. + * The response(s) detailed here SHALL only represent that the transaction + * was received and checked by the single node to which it was submitted.
    + * To obtain the result from _network consensus_, a client MUST submit a + * `getTransactionReceipts` query. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +31,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -28,23 +39,38 @@ 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). + * A message sent by a node in response to a transaction submission.
    + * This message only acknowledges that the individual node has checked + * the transaction, completed pre-check, and checked the fee offered. + * + * If the transaction fee is not sufficient, the `nodeTransactionPrecheckCode` + * value SHALL be `INSUFFICIENT_TX_FEE` and the `cost` field SHALL be the + * actual transaction fee, in tinybar, required.
    + * If the client requires acknowledgement of the network consensus result + * for a transaction, the client SHOULD request a transaction receipt or + * detailed transaction record. A client MAY also obtain network consensus + * results from a mirror node. */ message TransactionResponse { - /** - * The response code that indicates the current status of the transaction. - */ - ResponseCodeEnum nodeTransactionPrecheckCode = 1; + /** + * A pre-consensus response code. + *

    + * This response SHALL represent the response of the individual node, and + * SHALL NOT represent the consensus of the network. + */ + 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; + /** + * An approximate transaction fee. + *

    + * This value SHALL be `0` unless the `nodeTransactionPrecheckCode` is + * `INSUFFICIENT_TX_FEE`.
    + * This value SHOULD be an amount, in tinybar, that _would have_ succeeded + * at the time the transaction was submitted.
    + * Note that this amount is not guaranteed to succeed in a future + * transaction due to uncontrolled variables, such as network congestion, + * but should be considered a close approximation. + */ + uint64 cost = 2; } diff --git a/sdk/src/main/proto/tss_encryption_key.proto b/sdk/src/main/proto/tss_encryption_key.proto new file mode 100644 index 000000000..6cfa92df0 --- /dev/null +++ b/sdk/src/main/proto/tss_encryption_key.proto @@ -0,0 +1,46 @@ +/** + * # Tss Encryption Key Transaction + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ +syntax = "proto3"; + +package com.hedera.hapi.services.auxiliary.tss; + +/* + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +option java_package = "com.hedera.hapi.services.auxiliary.tss.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * A transaction body for sending the public TSS encryption key. + */ +message TssEncryptionKeyTransactionBody { + /** + * The raw bytes of the public TSS encryption key of the node sending the transaction. + *

    + * This value MUST be set.
    + * This value MUST NOT be empty.
    + */ + bytes publicTssEncryptionKey = 1; +} diff --git a/sdk/src/main/proto/tss_encryption_keys.proto b/sdk/src/main/proto/tss_encryption_keys.proto new file mode 100644 index 000000000..0b65d892e --- /dev/null +++ b/sdk/src/main/proto/tss_encryption_keys.proto @@ -0,0 +1,51 @@ +/** + * # Current and next TSS encryption keys + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ +syntax = "proto3"; + +package com.hedera.hapi.node.state.tss; + +/* + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +option java_package = "com.hedera.hapi.node.state.tss.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package +option java_multiple_files = true; + +/** + * A message containing a node's current and next TSS encryption keys, where + * the next key (if present) will be switched to the node's current key during + * the first transaction at the beginning of a staking period.
    + */ +message TssEncryptionKeys { + + /** + * If non-empty, a node's current TSS encryption key. + */ + bytes current_encryption_key = 1; + + /** + * If non-empty, the same node's next TSS encryption key. + */ + bytes next_encryption_key = 2; +} diff --git a/sdk/src/main/proto/tss_message.proto b/sdk/src/main/proto/tss_message.proto index 79eb06532..73c495069 100644 --- a/sdk/src/main/proto/tss_message.proto +++ b/sdk/src/main/proto/tss_message.proto @@ -10,7 +10,7 @@ */ syntax = "proto3"; -package com.hedera.hashgraph.hapi.services.auxiliary.tss; +package com.hedera.hapi.services.auxiliary.tss; /* * Copyright (C) 2024 Hedera Hashgraph, LLC @@ -28,7 +28,7 @@ package com.hedera.hashgraph.hapi.services.auxiliary.tss; * limitations under the License. */ -option java_package = "com.hedera.hashgraph.hapi.services.auxiliary.tss.legacy"; +option java_package = "com.hedera.hapi.services.auxiliary.tss.legacy"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; diff --git a/sdk/src/main/proto/tss_message_map_key.proto b/sdk/src/main/proto/tss_message_map_key.proto index 10f5220b4..bd3343156 100644 --- a/sdk/src/main/proto/tss_message_map_key.proto +++ b/sdk/src/main/proto/tss_message_map_key.proto @@ -10,7 +10,7 @@ */ syntax = "proto3"; -package com.hedera.hashgraph.hapi.node.state.tss; +package com.hedera.hapi.node.state.tss; /* * Copyright (C) 2024 Hedera Hashgraph, LLC @@ -28,7 +28,7 @@ package com.hedera.hashgraph.hapi.node.state.tss; * limitations under the License. */ -option java_package = "com.hedera.hashgraph.hapi.node.state.tss.legacy"; +option java_package = "com.hedera.hapi.node.state.tss.legacy"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; diff --git a/sdk/src/main/proto/tss_share_signature.proto b/sdk/src/main/proto/tss_share_signature.proto deleted file mode 100644 index 85dea8710..000000000 --- a/sdk/src/main/proto/tss_share_signature.proto +++ /dev/null @@ -1,88 +0,0 @@ -/** - * # Tss Share Signature - * Represents a transaction that submits a node's share signature on a block hash - * during the TSS (Threshold Signature Scheme) process. - * - * ### Keywords - * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - * document are to be interpreted as described in - * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in - * [RFC8174](https://www.ietf.org/rfc/rfc8174). - */ -syntax = "proto3"; - -package com.hedera.hashgraph.hapi.services.auxiliary.tss; - -/* - * Copyright (C) 2024 Hedera Hashgraph, LLC - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -option java_package = "com.hedera.hashgraph.hapi.services.auxiliary.tss.legacy"; -// <<>> This comment is special code for setting PBJ Compiler java package -option java_multiple_files = true; - -/** - * A TSS Share Signature transaction Body.
    - * This transaction body communicates a node's signature of a block hash - * using its private share within the TSS process. - * This transaction MUST be prioritized for low latency gossip transmission. - * - * ### Block Stream Effects - * This transaction body will be present in the block stream. This will not have - * any state changes or transaction output or transaction result. - */ -message TssShareSignatureTransactionBody { - /** - * A SHA2-384 Hash.
    - * This is the hash of the roster that includes the node whose - * share produced this share signature. - *

    - * This value is REQUIRED.
    - * This value MUST identify the network roster active at the time this - * share signature was produced.
    - * This share signature MUST be produced from a share distributed during - * the re-keying process for the identified roster. - */ - bytes roster_hash = 1; - - /** - * An index of the share from the node private shares.
    - * This is the index of the share that produced this share signature. - *

    - * This value is REQUIRED.
    - * The share referred to by this index MUST exist.
    - * The share index MUST be greater than or equal to 0. - */ - uint64 share_index = 2; - - /** - * A SHA2-384 hash.
    - * This is the hash of the message that was signed. - *

    - * This value is REQUIRED.
    - * The message signed MUST be a block hash. - */ - bytes message_hash = 3; - - /** - * The signature bytes.
    - * This is the signature generated by signing the block hash with the node's private share. - *

    - * This value is REQUIRED.
    - * This value MUST be a valid signature of the message hash with the node's private share. - */ - bytes share_signature = 4; -} diff --git a/sdk/src/main/proto/tss_vote.proto b/sdk/src/main/proto/tss_vote.proto index 3e59bc67d..97eb559a4 100644 --- a/sdk/src/main/proto/tss_vote.proto +++ b/sdk/src/main/proto/tss_vote.proto @@ -10,7 +10,7 @@ */ syntax = "proto3"; -package com.hedera.hashgraph.hapi.services.auxiliary.tss; +package com.hedera.hapi.services.auxiliary.tss; /* * Copyright (C) 2024 Hedera Hashgraph, LLC @@ -28,7 +28,7 @@ package com.hedera.hashgraph.hapi.services.auxiliary.tss; * limitations under the License. */ -option java_package = "com.hedera.hashgraph.hapi.services.auxiliary.tss.legacy"; +option java_package = "com.hedera.hapi.services.auxiliary.tss.legacy"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; diff --git a/sdk/src/main/proto/tss_vote_map_key.proto b/sdk/src/main/proto/tss_vote_map_key.proto index e7769068b..d5a0d6692 100644 --- a/sdk/src/main/proto/tss_vote_map_key.proto +++ b/sdk/src/main/proto/tss_vote_map_key.proto @@ -10,7 +10,7 @@ */ syntax = "proto3"; -package com.hedera.hashgraph.hapi.node.state.tss; +package com.hedera.hapi.node.state.tss; /* * Copyright (C) 2024 Hedera Hashgraph, LLC @@ -28,7 +28,7 @@ package com.hedera.hashgraph.hapi.node.state.tss; * limitations under the License. */ -option java_package = "com.hedera.hashgraph.hapi.node.state.tss.legacy"; +option java_package = "com.hedera.hapi.node.state.tss.legacy"; // <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; diff --git a/sdk/src/main/proto/unchecked_submit.proto b/sdk/src/main/proto/unchecked_submit.proto index b025b1464..ec7a74dd2 100644 --- a/sdk/src/main/proto/unchecked_submit.proto +++ b/sdk/src/main/proto/unchecked_submit.proto @@ -1,13 +1,27 @@ +/** + * # Unchecked Submit + * Submit a transaction to the network, bypassing all but the most minimal + * validation. + * + * > Important + * >> This transaction is obsolete and not supported.
    + * >> Any transaction of this type that is submitted SHALL fail with a + * >> `PRE_CHECK` result of `NOT_SUPPORTED`. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2021 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +33,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,12 +40,22 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; 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 pre-check. + * + * This transaction SHALL require `superuser` privileges + * (e.g. the `treasury` or `systemAdmin` accounts). */ message UncheckedSubmitBody { + option deprecated = true; /** - * The serialized bytes of the Transaction to be submitted without prechecks + * The serialized bytes of a `Transaction`. + *

    + * This transaction SHALL be deserialized and submitted for consensus + * with no further validation.
    + * Specifically, the transaction may violate basic limits and + * constraints such as size limits, minimum or maximum values, + * valid start time, fee calculations, etc... */ bytes transactionBytes = 1; } diff --git a/sdk/src/main/proto/util_prng.proto b/sdk/src/main/proto/util_prng.proto index 11ca5d01c..bba232c9e 100644 --- a/sdk/src/main/proto/util_prng.proto +++ b/sdk/src/main/proto/util_prng.proto @@ -1,13 +1,21 @@ +/** + * # Utility PRNG query + * A query to retrieve a deterministic pseudo-random value. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Network Services Protobuf - * ​ - * Copyright (C) 2018 - 2022 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +27,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -27,12 +34,23 @@ option java_package = "com.hedera.hashgraph.sdk.proto"; option java_multiple_files = true; /** - * Generates a pseudorandom number + * Request a deterministic pseudo-random number. + * + * The value returned SHALL be deterministic, but not easily predicted. + * The value returned SHALL NOT be suitable for cryptographic use. + * + * ### Block Stream Effects + * The result of this transaction is reported in a `UtilPrngOutput` message. */ message UtilPrngTransactionBody { - /** - * If provided and is positive, returns a 32-bit pseudorandom number from the given range in the transaction record. - * If not set or set to zero, will return a 384-bit pseudorandom number in the record. - */ - int32 range = 1; + /** + * A range for the requested value. + *

    + * If this is greater than `0`, the service SHALL return a 32-bit + * pseudo-random number between 0 and the value provided in the + * transaction record.
    + * If this is unset, zero, or negative; the service SHALL return a + * 384-bit unsigned pseudo-random number in the record. + */ + int32 range = 1; } diff --git a/sdk/src/main/proto/util_service.proto b/sdk/src/main/proto/util_service.proto index c920c2869..25a98c02c 100644 --- a/sdk/src/main/proto/util_service.proto +++ b/sdk/src/main/proto/util_service.proto @@ -1,13 +1,23 @@ +/** + * # Utility Service + * This service provides a transaction to generate a deterministic + * pseudo-random value, either a 32-bit integer within a requested range + * or a 384-bit byte array. + * + * ### Keywords + * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + * document are to be interpreted as described in + * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in + * [RFC8174](https://www.ietf.org/rfc/rfc8174). + */ syntax = "proto3"; package proto; -/*- - * ‌ - * Hedera Utility Services Protobuf - * ​ - * Copyright (C) 2018 - 2022 Hedera Hashgraph, LLC - * ​ +/* + * Copyright (C) 2018-2024 Hedera Hashgraph, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -19,7 +29,6 @@ package proto; * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * ‍ */ option java_package = "com.hedera.hashgraph.sdk.proto"; @@ -29,11 +38,21 @@ import "transaction_response.proto"; import "transaction.proto"; /** - * The requests and responses for different utility services. + * The Utility Service provides a pseudo-random number generator. + * + * The single gRPC call defined for this service simply reports a single + * pseudo-random number in the transaction record. That value may either + * be a 32-bit integer within a requested range, or a 384-bit byte array. + * + * ### Block Stream Effects + * The requested value is reported exclusively in a `UtilPrngOutput` message. */ service UtilService { - /** - * Generates a pseudorandom number. - */ - rpc prng (Transaction) returns (TransactionResponse); + /** + * Generate a pseudo-random value. + *

    + * The request body MUST be a + * [UtilPrngTransactionBody](#proto.UtilPrngTransactionBody) + */ + rpc prng (Transaction) returns (TransactionResponse); } diff --git a/sdk/src/test/java/com/hedera/hashgraph/sdk/AccountStakersQueryTest.java b/sdk/src/test/java/com/hedera/hashgraph/sdk/AccountStakersQueryTest.java deleted file mode 100644 index e0babaf15..000000000 --- a/sdk/src/test/java/com/hedera/hashgraph/sdk/AccountStakersQueryTest.java +++ /dev/null @@ -1,31 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -package com.hedera.hashgraph.sdk; - -import com.hedera.hashgraph.sdk.proto.QueryHeader; -import io.github.jsonSnapshot.SnapshotMatcher; -import org.junit.jupiter.api.AfterAll; -import org.junit.jupiter.api.BeforeAll; -import org.junit.jupiter.api.Test; - -public class AccountStakersQueryTest { - @BeforeAll - public static void beforeAll() { - SnapshotMatcher.start(Snapshot::asJsonString); - } - - @AfterAll - public static void afterAll() { - SnapshotMatcher.validateSnapshots(); - } - - @Test - void shouldSerialize() { - var builder = com.hedera.hashgraph.sdk.proto.Query.newBuilder(); - new AccountStakersQuery() - .setAccountId(AccountId.fromString("0.0.5005")) - .setMaxQueryPayment(Hbar.fromTinybars(100_000)) - .onMakeRequest(builder, QueryHeader.newBuilder().build()); - SnapshotMatcher.expect(builder.build().toString().replaceAll("@[A-Za-z0-9]+", "")) - .toMatchSnapshot(); - } -} diff --git a/sdk/src/test/java/com/hedera/hashgraph/sdk/AccountStakersQueryTest.snap b/sdk/src/test/java/com/hedera/hashgraph/sdk/AccountStakersQueryTest.snap deleted file mode 100644 index 20f2e1b40..000000000 --- a/sdk/src/test/java/com/hedera/hashgraph/sdk/AccountStakersQueryTest.snap +++ /dev/null @@ -1,3 +0,0 @@ -com.hedera.hashgraph.sdk.AccountStakersQueryTest.shouldSerialize=[ - "# com.hedera.hashgraph.sdk.proto.Query\ncrypto_get_proxy_stakers {\n account_i_d {\n account_num: 5005\n realm_num: 0\n shard_num: 0\n }\n header {\n }\n}" -] diff --git a/sdk/src/test/java/com/hedera/hashgraph/sdk/TopicInfoTest.snap b/sdk/src/test/java/com/hedera/hashgraph/sdk/TopicInfoTest.snap index b11a2ea2f..287dbef6e 100644 --- a/sdk/src/test/java/com/hedera/hashgraph/sdk/TopicInfoTest.snap +++ b/sdk/src/test/java/com/hedera/hashgraph/sdk/TopicInfoTest.snap @@ -14,5 +14,5 @@ com.hedera.hashgraph.sdk.TopicInfoTest.toBytes=[ com.hedera.hashgraph.sdk.TopicInfoTest.toProtobuf=[ - "# com.hedera.hashgraph.sdk.proto.ConsensusGetTopicInfoResponse@a2d5b392\ntopic_i_d {\n realm_num: 0\n shard_num: 0\n topic_num: 0\n}\ntopic_info {\n admin_key {\n ed25519: \"\\340\\310\\354\\'X\\245\\207\\237\\372\\302&\\241<\\fQky\\236r\\343QA\\240\\335\\202\\217\\224\\323y\\210\\244\\267\"\n }\n auto_renew_account {\n account_num: 4\n realm_num: 0\n shard_num: 0\n }\n auto_renew_period {\n seconds: 432000\n }\n expiration_time {\n nanos: 4000000\n seconds: 0\n }\n ledger_id: \"\\001\"\n memo: \"1\"\n running_hash: \"\\002\"\n sequence_number: 3\n submit_key {\n ed25519: \"\\340\\310\\354\\'X\\245\\207\\237\\372\\302&\\241<\\fQky\\236r\\343QA\\240\\335\\202\\217\\224\\323y\\210\\244\\267\"\n }\n}" -] + "# com.hedera.hashgraph.sdk.proto.ConsensusGetTopicInfoResponse@1902aaed\ntopic_i_d {\n realm_num: 0\n shard_num: 0\n topic_num: 0\n}\ntopic_info {\n admin_key {\n ed25519: \"\\340\\310\\354\\'X\\245\\207\\237\\372\\302&\\241<\\fQky\\236r\\343QA\\240\\335\\202\\217\\224\\323y\\210\\244\\267\"\n }\n auto_renew_account {\n account_num: 4\n realm_num: 0\n shard_num: 0\n }\n auto_renew_period {\n seconds: 432000\n }\n expiration_time {\n nanos: 4000000\n seconds: 0\n }\n ledger_id: \"\\001\"\n memo: \"1\"\n running_hash: \"\\002\"\n sequence_number: 3\n submit_key {\n ed25519: \"\\340\\310\\354\\'X\\245\\207\\237\\372\\302&\\241<\\fQky\\236r\\343QA\\240\\335\\202\\217\\224\\323y\\210\\244\\267\"\n }\n}" +] \ No newline at end of file diff --git a/sdk/src/testIntegration/java/com/hedera/hashgraph/sdk/test/integration/AccountStakersIntegrationTest.java b/sdk/src/testIntegration/java/com/hedera/hashgraph/sdk/test/integration/AccountStakersIntegrationTest.java deleted file mode 100644 index cdc116159..000000000 --- a/sdk/src/testIntegration/java/com/hedera/hashgraph/sdk/test/integration/AccountStakersIntegrationTest.java +++ /dev/null @@ -1,29 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -package com.hedera.hashgraph.sdk.test.integration; - -import static org.assertj.core.api.Assertions.assertThatExceptionOfType; - -import com.hedera.hashgraph.sdk.AccountStakersQuery; -import com.hedera.hashgraph.sdk.Hbar; -import com.hedera.hashgraph.sdk.PrecheckStatusException; -import com.hedera.hashgraph.sdk.Status; -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -class AccountStakersIntegrationTest { - @Test - @DisplayName("Cannot query account stakers since it is not supported") - void cannotQueryAccountStakersSinceItIsNotSupported() throws Exception { - try (var testEnv = new IntegrationTestEnv(1)) { - - assertThatExceptionOfType(PrecheckStatusException.class) - .isThrownBy(() -> { - new AccountStakersQuery() - .setAccountId(testEnv.operatorId) - .setMaxQueryPayment(new Hbar(1)) - .execute(testEnv.client); - }) - .withMessageContaining(Status.NOT_SUPPORTED.toString()); - } - } -}