hiero-ledger · 0xivanov · Feb 13, 2025 · Jan 17, 2025 · Jan 17, 2025 · Feb 13, 2025
@@ -18,8 +18,14 @@
 import javax.annotation.Nullable;
 
 /**
- * This transaction type is for approving account allowance.
- */
+ * # 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).
+ *
+ **/
 public class AccountAllowanceApproveTransaction extends Transaction<AccountAllowanceApproveTransaction> {
     private final List<HbarAllowance> hbarAllowances = new ArrayList<>();
     private final List<TokenAllowance> tokenAllowances = new ArrayList<>();

@@ -18,7 +18,21 @@
 import javax.annotation.Nullable;
 
 /**
- * This transaction type is for deleting an account allowance.
+ * 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
  */
 public class AccountAllowanceDeleteTransaction
         extends com.hedera.hashgraph.sdk.Transaction<AccountAllowanceDeleteTransaction> {

@@ -14,9 +14,18 @@
 import java.util.Objects;
 import javax.annotation.Nullable;
 
-/**
+/*
  * Create a new Hedera™ account.
+ *
+ * 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.
+ *
+ * ### Block Stream Effects
+ * The newly created account SHALL be included in State Changes.
  */
+
 public final class AccountCreateTransaction extends Transaction<AccountCreateTransaction> {
     @Nullable
     private AccountId proxyAccountId = null;
@@ -82,10 +91,14 @@ public Key getKey() {
     }
 
     /**
-     * Set the key for this account.
-     *
-     * <p>The key that must sign each transfer out of the account. If receiverSignatureRequired 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.
+     * <p>
+     * This field is REQUIRED.
+     * This `Key` MUST NOT be an empty `KeyList` and MUST contain at least one
+     * "primitive" (i.e. cryptographic) key value.
      *
      * @param key the key for this account.
      * @return {@code this}
@@ -164,7 +177,10 @@ public Hbar getInitialBalance() {
     }
 
     /**
-     * Set the initial amount to transfer into this account.
+     * An amount, in tinybar, to deposit to the newly created account.
+     * <p>
+     * The deposited amount SHALL be debited to the "payer" account for this
+     * transaction.
      *
      * @param initialBalance the initial balance.
      * @return {@code this}
@@ -186,10 +202,14 @@ public boolean getReceiverSignatureRequired() {
     }
 
     /**
-     * Set to true to require this account to sign any transfer of hbars to this account.
-     *
-     * <p>All transfers of hbars from this account must always be signed. This property only affects
-     * transfers to this account.
+     * A flag indicating the account holder must authorize all incoming
+     * token transfers.
+     * <p>
+     * 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).<br/>
+     * If this flag is set, then the account key (`key` field) MUST sign
+     * this create transaction, in addition to the transaction payer.
      *
      * @param receiveSignatureRequired true to require a signature when receiving hbars.
      * @return {@code this}
@@ -218,6 +238,9 @@ public AccountId getProxyAccountId() {
      *
      * Set the ID of the account to which this account is proxy staked.
      *
+     * Use `staked_id` instead.<br/>
+     * An account identifier for a staking proxy.
+     *
      * @param proxyAccountId the proxy account ID.
      * @return {@code this}
      */
@@ -268,7 +291,15 @@ public int getMaxAutomaticTokenAssociations() {
     }
 
     /**
-     * Grant an amount of tokens.
+     * A maximum number of tokens that can be auto-associated
+     * with this account.<br/>
+     * By default this value is 0 for all accounts except for automatically
+     * created accounts (e.g. smart contracts), which default to -1.
+     * <p>
+     * If this value is `0`, then this account MUST manually associate to
+     * a token before holding or transacting in that token.<br/>
+     * This value MAY also be `-1` to indicate no limit.<br/>
+     * This value MUST NOT be less than `-1`.
      *
      * @param amount                    the amount of tokens
      * @return                          {@code this}
@@ -289,7 +320,10 @@ public String getAccountMemo() {
     }
 
     /**
-     * Assign a memo to the account.
+     * A short description of this Account.
+     * <p>
+     * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes`
+     * (default 100) bytes when encoded as UTF-8.
      *
      * @param memo                      the memo
      * @return                          {@code this}
@@ -335,7 +369,13 @@ public Long getStakedNodeId() {
     }
 
     /**
-     * Set the node to which this account will stake
+     * ID of the node this account is staked to.
+     * <p>
+     * If this account is not currently staking its balances, then this
+     * field, if set, SHALL be the sentinel value of `-1`.<br/>
+     * 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.
      *
      * @param stakedNodeId ID of the node this account will be staked to.
      * @return {@code this}

@@ -13,11 +13,21 @@
 import javax.annotation.Nullable;
 
 /**
- * Marks an account as deleted, moving all its current hbars to another account.
- * <p>
- * 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.<br/>
+ * 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.<br/>
+ * A deleted account SHALL remain in state until it expires.<br/>
+ * Transfers that would increase the balance of a deleted account
+ * SHALL fail.<br/>
+ * A deleted account MAY be subject of a `cryptoUpdate` transaction to extend
+ * its expiration.<br/>
+ * When a deleted account expires it SHALL be removed entirely, and SHALL NOT
+ * be archived.
+ *
+ * ### Block Stream Effects
+ * None
  */
 public final class AccountDeleteTransaction extends Transaction<AccountDeleteTransaction> {
     @Nullable
@@ -65,7 +75,14 @@ public AccountId getAccountId() {
     }
 
     /**
-     * Sets the account ID which should be deleted.
+     * An account identifier.
+     * <p>
+     * This account SHALL be deleted if this transaction succeeds.<br/>
+     * This account SHOULD NOT hold any balance other than HBAR.<br/>
+     * If this account _does_ hold balances, the `transferAccountID` value
+     * MUST be set to a valid transfer account.<br/>
+     * This account MUST sign this transaction.<br/>
+     * This field MUST be set to a valid account identifier.
      *
      * @param deleteAccountId The AccountId to be set
      * @return {@code this}
@@ -88,7 +105,13 @@ public AccountId getTransferAccountId() {
     }
 
     /**
-     * Sets the account ID which will receive all remaining hbars.
+     * An account identifier.
+     * <p>
+     * The identified account SHALL receive all tokens, token balances,
+     * and non-fungible/unique from the deleted account.<br/>
+     * The identified account MUST sign this transaction.<br/>
+     * If not set, the account to be deleted MUST NOT have a balance in any
+     * token, a balance in HBAR, or hold any NFT.
      *
      * @param transferAccountId The AccountId to be set
      * @return {@code this}

@@ -18,20 +18,23 @@
 import javax.annotation.Nullable;
 
 /**
- * Change properties for the given account.
- * <p>
- * Any null field is ignored (left unchanged).
- * <p>
- * This transaction must be signed by the existing key for this account.
- * <p>
- * 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.
- * <p>
- * When extending the expiration date, the cost is affected by the size
- * of the list of attached claims, and of the keys
- * associated with the claims and the account.
+ * 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
  */
 public final class AccountUpdateTransaction extends Transaction<AccountUpdateTransaction> {
     @Nullable
@@ -132,7 +135,12 @@ public Key getKey() {
     }
 
     /**
-     * Sets the new key.
+     * An account key.<br/>
+     * This may be a "primitive" key (a singly cryptographic key), or a
+     * composite key.
+     * <p>
+     * If set, this key MUST be a valid key.<br/>
+     * If set, the previous key and new key MUST both sign this transaction.
      *
      * @param key The Key to be set
      * @return {@code this}
@@ -212,8 +220,14 @@ public Instant getExpirationTime() {
     }
 
     /**
-     * Sets 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.
+     * <p>
+     * For this purpose, `epoch` SHALL be the UNIX epoch with 0
+     * at `1970-01-01T00:00:00.000Z`.<br/>
+     * If set, this value MUST be later than the current consensus time.<br/>
+     * If set, this value MUST be earlier than the current consensus time
+     * extended by the current maximum expiration time configured for the
+     * network.
      *
      * @param expirationTime The Instant to be set as the expiration time
      * @return {@code this}
@@ -236,10 +250,14 @@ public Duration getAutoRenewPeriod() {
     }
 
     /**
-     * Sets the duration in which it will automatically extend the expiration period.
+     * A duration to extend account expiration.<br/>
+     * An amount of time, in seconds, to extend the expiration date for this
+     * account when _automatically_ renewed.
      * <p>
-     * If it doesn't have enough balance, it extends as long as possible.
-     * If it is empty when it expires, then it is deleted.
+     * This duration MUST be between the current configured minimum and maximum
+     * values defined for the network.<br/>
+     * This duration SHALL be applied only when _automatically_ extending the
+     * account expiration.
      *
      * @param autoRenewPeriod The Duration to be set for auto renewal
      * @return {@code this}
@@ -262,8 +280,10 @@ public Boolean getReceiverSignatureRequired() {
     }
 
     /**
-     * Sets whether this account's key must sign any transaction
-     * depositing into this account (in addition to all withdrawals).
+     * Removed to distinguish between unset and a default value.<br/>
+     * 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.
      *
      * @param receiverSignatureRequired The bool to be set
      * @return {@code this}
@@ -285,7 +305,15 @@ public Integer getMaxAutomaticTokenAssociations() {
     }
 
     /**
-     * Grant an amount of tokens.
+     * A maximum number of tokens that can be auto-associated
+     * with this account.<br/>
+     * By default this value is 0 for all accounts except for automatically
+     * created accounts (i.e smart contracts) which default to -1.
+     * <p>
+     * If this value is `0`, then this account MUST manually associate to
+     * a token before holding or transacting in that token.<br/>
+     * This value MAY also be `-1` to indicate no limit.<br/>
+     * If set, this value MUST NOT be less than `-1`.<br/>
      *
      * @param amount                    the amount of tokens
      * @return                          {@code this}
@@ -307,7 +335,10 @@ public String getAccountMemo() {
     }
 
     /**
-     * Assign a memo to the account.
+     * A short description of this Account.
+     * <p>
+     * This value, if set, MUST NOT exceed `transaction.maxMemoUtf8Bytes`
+     * (default 100) bytes when encoded as UTF-8.
      *
      * @param memo                      the memo
      * @return                          {@code this}
@@ -341,7 +372,10 @@ public AccountId getStakedAccountId() {
     }
 
     /**
-     * Set the account to which this account will stake
+     * ID of the account to which this account is staking its balances.
+     * <p>
+     * If this account is not currently staking its balances, then this
+     * field, if set, MUST be the sentinel value of `0.0.0`.
      *
      * @param stakedAccountId ID of the account to which this account will stake.
      * @return {@code this}
@@ -376,7 +410,13 @@ public Long getStakedNodeId() {
     }
 
     /**
-     * Set the node to which this account will stake
+     * ID of the node this account is staked to.
+     * <p>
+     * If this account is not currently staking its balances, then this
+     * field, if set, SHALL be the sentinel value of `-1`.<br/>
+     * 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.
      *
      * @param stakedNodeId ID of the node this account will be staked to.
      * @return {@code this}
@@ -411,7 +451,11 @@ public Boolean getDeclineStakingReward() {
     }
 
     /**
-     * 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.
+     * <p>
+     * This account MAY still stake its balances, but SHALL NOT receive reward
+     * payments for doing so, if this value is set, and `true`.
      *
      * @param declineStakingReward - If true, the account declines receiving a staking reward. The default value is false.
      * @return {@code this}