Protocol Documentation

Table of Contents

AccountBalanceFile.proto

Top

AllAccountBalances

Includes all currency balances (both hbar and token) of all accounts in the ledger.

FieldTypeLabelDescription
consensusTimestamp Timestamp

An instant in consensus time

allAccounts SingleAccountBalances repeated

The list of account balances for all accounts, after handling all transactions with consensus timestamp up to and including the above instant

SingleAccountBalances

Includes all currency balances (both hbar and token) of a single account in the ledger.

FieldTypeLabelDescription
accountID AccountID

The account

hbarBalance uint64

The account's hbar balance

tokenUnitBalances TokenUnitBalance repeated

The list of the account's token balances

TokenUnitBalance

FieldTypeLabelDescription
tokenId TokenID

A unique token id

balance uint64

A number of transferable units of the identified token

BasicTypes.proto

Top

AccountAmount

An account, and the amount that it sends or receives during a cryptocurrency or token transfer.

FieldTypeLabelDescription
accountID AccountID

The Account ID that sends/receives cryptocurrency or tokens

amount sint64

The amount of tinybars (for Crypto transfers) or in the lowest denomination (for Token transfers) that the account sends(negative) or receives(positive)

AccountID

The ID for an a cryptocurrency account

FieldTypeLabelDescription
shardNum int64

The shard number (nonnegative)

realmNum int64

The realm number (nonnegative)

accountNum int64

A nonnegative account number unique within its realm

ContractID

The ID for a smart contract instance

FieldTypeLabelDescription
shardNum int64

The shard number (nonnegative)

realmNum int64

The realm number (nonnegative)

contractNum int64

A nonnegative number unique within its realm

CurrentAndNextFeeSchedule

This contains two Fee Schedules with expiry timestamp.

FieldTypeLabelDescription
currentFeeSchedule FeeSchedule

Contains current Fee Schedule

nextFeeSchedule FeeSchedule

Contains next Fee Schedule

FeeComponents

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.

FieldTypeLabelDescription
min int64

A minimum, the calculated fee must be greater than this value

max int64

A maximum, the calculated fee must be less than this value

constant int64

A constant contribution to the fee

bpt int64

The price of bandwidth consumed by a transaction, measured in bytes

vpt int64

The price per signature verification for a transaction

rbh int64

The price of RAM consumed by a transaction, measured in byte-hours

sbh int64

The price of storage consumed by a transaction, measured in byte-hours

gas int64

The price of computation for a smart contract transaction, measured in gas

tv int64

The price per hbar transferred for a transfer

bpr int64

The price of bandwidth for data retrieved from memory for a response, measured in bytes

sbpr int64

The price of bandwidth for data retrieved from disk for a response, measured in bytes

FeeData

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.

FieldTypeLabelDescription
nodedata FeeComponents

Fee paid to the submitting node

networkdata FeeComponents

Fee paid to the network for processing a transaction into consensus

servicedata FeeComponents

Fee paid to the network for providing the service associated with the transaction; for instance, storing a file

FeeSchedule

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.

FieldTypeLabelDescription
transactionFeeSchedule TransactionFeeSchedule repeated

List of price coefficients for network resources

expiryTime TimestampSeconds

FeeSchedule expiry time

FileID

The ID for a file

FieldTypeLabelDescription
shardNum int64

The shard number (nonnegative)

realmNum int64

The realm number (nonnegative)

fileNum int64

A nonnegative File number unique within its realm

Key

A Key can be a public key from one of the three supported systems (ed25519, RSA-3072, ECDSA with p384). Or, it can be the ID of a smart contract instance, which is authorized to act as if it had a key. If an account has an ed25519 key associated with it, then the corresponding private key must sign any transaction to transfer cryptocurrency out of it. And similarly for RSA and ECDSA.

A Key can be a smart contract ID, which means that smart contract is to authorize operations as if it had signed with a key that it owned. The smart contract doesn't actually have a key, and doesn't actually sign a transaction. But it's as if a virtual transaction were created, and the smart contract signed it with a private key.

A key can be a "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 list of keys. 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 can contain a ThresholdKey or KeyList, which in turn contain a Key, so this mutual recursion would allow nesting arbitrarily deep. A ThresholdKey which contains a list of primitive keys (e.g., ed25519) has 3 levels: ThresholdKey -> KeyList -> Key. A KeyList which contains several primitive keys (e.g., ed25519) has 2 levels: KeyList -> Key. A Key with 2 levels of nested ThresholdKeys has 7 levels: Key -> ThresholdKey -> KeyList -> Key -> ThresholdKey -> KeyList -> Key.

Each Key should not have more than 46 levels, which implies 15 levels of nested ThresholdKeys.

FieldTypeLabelDescription
contractID ContractID

smart contract instance that is authorized as if it had signed with a key

ed25519 bytes

ed25519 public key bytes

RSA_3072 bytes

RSA-3072 public key bytes

ECDSA_384 bytes

ECDSA with the p-384 curve public key bytes

thresholdKey ThresholdKey

a threshold N followed by a list of M keys, any N of which are required to form a valid signature

keyList KeyList

A list of Keys of the Key type.

KeyList

A list of keys

FieldTypeLabelDescription
keys Key repeated

list of keys

NodeAddress

The metadata for a Node – including IP Address, and the crypto account associated with the Node.

FieldTypeLabelDescription
ipAddress bytes

The ip address of the Node with separator & octets

portno int32

The port number of the grpc server for the node

memo bytes

The memo field of the node (usage to store account ID is deprecated)

RSA_PubKey string

The RSA public key of the node

nodeId int64

A non-sequential identifier for the node

nodeAccountId AccountID

The account to be paid for queries and transactions sent to this node

nodeCertHash bytes

A hash of the X509 cert used for gRPC traffic to this node

NodeAddressBook

A list of nodes and their metadata.

FieldTypeLabelDescription
nodeAddress NodeAddress repeated

Contains multiple Node Address for the network

RealmID

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.

FieldTypeLabelDescription
shardNum int64

The shard number (nonnegative)

realmNum int64

The realm number (nonnegative)

ScheduleID

Unique identifier for a Schedule

FieldTypeLabelDescription
shardNum int64

A nonnegative shard number

realmNum int64

A nonnegative realm number

scheduleNum int64

A nonnegative schedule number

SemanticVersion

FieldTypeLabelDescription
major int32

Increases with incompatible API changes

minor int32

Increases with backwards-compatible new functionality

patch int32

Increases with backwards-compatible bug fixes

ServicesConfigurationList

FieldTypeLabelDescription
nameValue Setting repeated

list of name value pairs of the application properties

Setting

FieldTypeLabelDescription
name string

name of the property

value string

value of the property

data bytes

any data associated with property

ShardID

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.

FieldTypeLabelDescription
shardNum int64

the shard number (nonnegative)

Signature

A Signature corresponding to a Key. It is a sequence of bytes holding a public key signature from one of the three supported systems (ed25519, RSA-3072, ECDSA with p384). Or, it can be a list of signatures corresponding to a single threshold key. Or, it can be the ID of a smart contract instance, which is authorized to act as if it had a key. If an account has an ed25519 key associated with it, then the corresponding private key must sign any transaction to transfer cryptocurrency out of it. If it has a smart contract ID associated with it, then that smart contract is allowed to transfer cryptocurrency out of it. The smart contract doesn't actually have a key, and doesn't actually sign a transaction. But it's as if a virtual transaction were created, and the smart contract signed it with a private key. A key can also be a "threshold key", which means a list of M keys, any N of which must sign in order for the threshold signature to be considered valid. The keys within a threshold signature may themselves be threshold signatures, to allow complex signature requirements (this nesting is not supported in the currently, but will be supported in a future version of API). If a Signature message is missing the "signature" field, then this is considered to be a null signature. That is useful in cases such as threshold signatures, where some of the signatures can be null.

The definition of Key uses mutual recursion, so it allows nesting that is arbitrarily deep. But the current API only accepts Key messages up to 3 levels deep, such as a list of threshold keys, each of which is a list of primitive keys. Therefore, the matching Signature will have the same limitation. This restriction may be relaxed in future versions of the API, to allow deeper nesting.

This message is deprecated and succeeded by SignaturePair and SignatureMap messages.

FieldTypeLabelDescription
contract bytes

smart contract virtual signature (always length zero)

ed25519 bytes

ed25519 signature bytes

RSA_3072 bytes

RSA-3072 signature bytes

ECDSA_384 bytes

ECDSA p-384 signature bytes

thresholdSignature ThresholdSignature

A list of signatures for a single N-of-M threshold Key. This must be a list of exactly M signatures, at least N of which are non-null.

signatureList SignatureList

A list of M signatures, each corresponding to a Key in a KeyList of the same length.

SignatureList

The signatures corresponding to a KeyList of the same length.

This message is deprecated and succeeded by SignaturePair and SignatureMap messages.

FieldTypeLabelDescription
sigs Signature repeated

each signature corresponds to a Key in the KeyList

SignatureMap

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.

FieldTypeLabelDescription
sigPair SignaturePair repeated

Each signature pair corresponds to a unique Key required to sign the transaction.

SignaturePair

The client may use any number of bytes from 0 to the whole length of the public key for pubKeyPrefix.

If 0 bytes is used, then it is assumed that only one public key is used to sign.

FieldTypeLabelDescription
pubKeyPrefix bytes

First few bytes of the public key

contract bytes

smart contract virtual signature (always length zero)

ed25519 bytes

ed25519 signature

RSA_3072 bytes

RSA-3072 signature

ECDSA_384 bytes

ECDSA p-384 signature

ThresholdKey

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.

FieldTypeLabelDescription
threshold uint32

A valid signature set must have at least this many signatures

keys KeyList

List of all the keys that can sign

ThresholdSignature

A signature corresponding to a ThresholdKey. For an N-of-M threshold key, this is a list of M signatures, at least N of which must be non-null.

This message is deprecated and succeeded by SignaturePair and SignatureMap messages.

FieldTypeLabelDescription
sigs SignatureList

for an N-of-M threshold key, this is a list of M signatures, at least N of which must be non-null

TokenBalance

A number of transferable units of a certain token.

The transferable unit of a token is its smallest denomination, as given by the token's decimals property---each minted token contains 10decimals transferable units. For example, we could think of the cent as the transferable unit of the US dollar (decimals=2); and the tinybar as the transferable unit of hbar (decimals=8).

Transferable units are not directly comparable across different tokens.

FieldTypeLabelDescription
tokenId TokenID

A unique token id

balance uint64

A number of transferable units of the identified token

decimals uint32

Tokens divide into <tt>10<sup>decimals</sup></tt> pieces

TokenBalances

A sequence of token balances

FieldTypeLabelDescription
tokenBalances TokenBalance repeated

TokenID

Unique identifier for a token

FieldTypeLabelDescription
shardNum int64

A nonnegative shard number

realmNum int64

A nonnegative realm number

tokenNum int64

A nonnegative token number

TokenRelationship

Token's information related to the given Account

FieldTypeLabelDescription
tokenId TokenID

The ID of the token

symbol string

The Symbol of the token

balance uint64

The balance that the Account holds in the smallest denomination

kycStatus TokenKycStatus

The KYC status of the account (KycNotApplicable, Granted or Revoked). If the token does not have KYC key, KycNotApplicable is returned

freezeStatus TokenFreezeStatus

The Freeze status of the account (FreezeNotApplicable, Frozen or Unfrozen). If the token does not have Freeze key, FreezeNotApplicable is returned

decimals uint32

Tokens divide into <tt>10<sup>decimals</sup></tt> pieces

TokenTransferList

A list of token IDs and amounts representing the transferred out (negative) or into (positive) amounts, represented in the lowest denomination of the token

FieldTypeLabelDescription
token TokenID

The ID of the token

transfers AccountAmount repeated

Multiple list of AccountAmounts, each of which has an account and amount

TopicID

Unique identifier for a topic (used by the consensus service)

FieldTypeLabelDescription
shardNum int64

The shard number (nonnegative)

realmNum int64

The realm number (nonnegative)

topicNum int64

Unique topic identifier within a realm (nonnegative).

TransactionFeeSchedule

The fees for a specific transaction or query based on the fee data.

FieldTypeLabelDescription
hederaFunctionality HederaFunctionality

A particular transaction or query

feeData FeeData

Resource price coefficients

TransactionID

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

- Scheduled Transactions should be submitted with only nonce populated (if desired). Nonce is an additional option presented to users so that they can create multiple sequential Scheduled Transactions that have the same transaction body.

FieldTypeLabelDescription
transactionValidStart Timestamp

The transaction is invalid if consensusTimestamp < transactionID.transactionStartValid

accountID AccountID

The Account ID that paid for this transaction

scheduled bool

Whether the Transaction is of type Scheduled or no

nonce bytes

Used to manipulate the uniqueness check for idempotent schedule transaction creation

TransferList

A list of accounts and amounts to transfer out of each account (negative) or into it (positive).

FieldTypeLabelDescription
accountAmounts AccountAmount repeated

Multiple list of AccountAmount pairs, each of which has an account and an amount to transfer into it (positive) or out of it (negative)

HederaFunctionality

The transactions and queries supported by Hedera Hashgraph.

NameNumberDescription
NONE 0

UNSPECIFIED - Need to keep first value as unspecified because first element is ignored and not parsed (0 is ignored by parser)

CryptoTransfer 1

crypto transfer

CryptoUpdate 2

crypto update account

CryptoDelete 3

crypto delete account

CryptoAddLiveHash 4

Add a livehash to a crypto account

CryptoDeleteLiveHash 5

Delete a livehash from a crypto account

ContractCall 6

Smart Contract Call

ContractCreate 7

Smart Contract Create Contract

ContractUpdate 8

Smart Contract update contract

FileCreate 9

File Operation create file

FileAppend 10

File Operation append file

FileUpdate 11

File Operation update file

FileDelete 12

File Operation delete file

CryptoGetAccountBalance 13

crypto get account balance

CryptoGetAccountRecords 14

crypto get account record

CryptoGetInfo 15

Crypto get info

ContractCallLocal 16

Smart Contract Call

ContractGetInfo 17

Smart Contract get info

ContractGetBytecode 18

Smart Contract, get the byte code

GetBySolidityID 19

Smart Contract, get by solidity ID

GetByKey 20

Smart Contract, get by key

CryptoGetLiveHash 21

Get a live hash from a crypto account

CryptoGetStakers 22

Crypto, get the stakers for the node

FileGetContents 23

File Operations get file contents

FileGetInfo 24

File Operations get the info of the file

TransactionGetRecord 25

Crypto get the transaction records

ContractGetRecords 26

Contract get the transaction records

CryptoCreate 27

crypto create account

SystemDelete 28

system delete file

SystemUndelete 29

system undelete file

ContractDelete 30

delete contract

Freeze 31

freeze

CreateTransactionRecord 32

Create Tx Record

CryptoAccountAutoRenew 33

Crypto Auto Renew

ContractAutoRenew 34

Contract Auto Renew

GetVersionInfo 35

Get Version

TransactionGetReceipt 36

Transaction Get Receipt

ConsensusCreateTopic 50

Create Topic

ConsensusUpdateTopic 51

Update Topic

ConsensusDeleteTopic 52

Delete Topic

ConsensusGetTopicInfo 53

Get Topic information

ConsensusSubmitMessage 54

Submit message to topic

UncheckedSubmit 55

TokenCreate 56

Create Token

TokenGetInfo 58

Get Token information

TokenFreezeAccount 59

Freeze Account

TokenUnfreezeAccount 60

Unfreeze Account

TokenGrantKycToAccount 61

Grant KYC to Account

TokenRevokeKycFromAccount 62

Revoke KYC from Account

TokenDelete 63

Delete Token

TokenUpdate 64

Update Token

TokenMint 65

Mint tokens to treasury

TokenBurn 66

Burn tokens from treasury

TokenAccountWipe 67

Wipe token amount from Account holder

TokenAssociateToAccount 68

Associate tokens to an account

TokenDissociateFromAccount 69

Dissociate tokens from an account

ScheduleCreate 70

Create Scheduled Transaction

ScheduleDelete 71

Delete Scheduled Transaction

ScheduleSign 72

Sign Scheduled Transaction

ScheduleGetInfo 73

Get Scheduled Transaction Information

TokenFreezeStatus

Possible Freeze statuses returned on TokenGetInfoQuery or CryptoGetInfoResponse in TokenRelationship

NameNumberDescription
FreezeNotApplicable 0

Frozen 1

Unfrozen 2

TokenKycStatus

Possible KYC statuses returned on TokenGetInfoQuery or CryptoGetInfoResponse in TokenRelationship

NameNumberDescription
KycNotApplicable 0

Granted 1

Revoked 2

ConsensusCreateTopic.proto

Top

ConsensusCreateTopicTransactionBody

See [ConsensusService.createTopic()](#proto.ConsensusService)

FieldTypeLabelDescription
memo string

Short publicly visible memo about the topic. No guarantee of uniqueness.

adminKey Key

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.

submitKey Key

Access control for submitMessage. If unspecified, no access control is performed on ConsensusService.submitMessage (all submissions are allowed).

autoRenewPeriod Duration

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.

autoRenewAccount AccountID

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.

ConsensusDeleteTopic.proto

Top

ConsensusDeleteTopicTransactionBody

See [ConsensusService.deleteTopic()](#proto.ConsensusService)

FieldTypeLabelDescription
topicID TopicID

Topic identifier.

ConsensusGetTopicInfo.proto

Top

ConsensusGetTopicInfoQuery

See [ConsensusService.getTopicInfo()](#proto.ConsensusService)

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

topicID TopicID

The Topic for which information is being requested

ConsensusGetTopicInfoResponse

Retrieve the parameters of and state of a consensus topic.

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither.

topicID TopicID

Topic identifier.

topicInfo ConsensusTopicInfo

Current state of the topic

ConsensusService.proto

Top

ConsensusService

The Consensus Service provides the ability for Hedera Hashgraph to provide aBFT consensus as to the order and

validity of messages submitted to a *topic*, as well as a *consensus timestamp* for those messages.

Automatic renewal can be configured via an autoRenewAccount.

Any time an autoRenewAccount is added to a topic, that createTopic/updateTopic transaction must be signed by

the autoRenewAccount.

The autoRenewPeriod on an account must currently be set a value in createTopic between MIN_AUTORENEW_PERIOD (6999999

seconds) and MAX_AUTORENEW_PERIOD (8000001 seconds). During creation this sets the initial expirationTime of the

topic (see more below).

If no adminKey is on a topic, there may not be an autoRenewAccount on the topic, deleteTopic is not allowed,

and the only change allowed via an updateTopic is to extend the expirationTime.

If an adminKey is on a topic, every updateTopic and deleteTopic transaction must be signed by the adminKey, except

for updateTopics which only extend the topic's expirationTime (no adminKey authorization required).

If an updateTopic modifies the adminKey of a topic, the transaction signatures on the updateTopic must fulfill both

the pre-update and post-update adminKey signature requirements.

Mirrornet ConsensusService may be used to subscribe to changes on the topic, including changes to the topic

definition and the consensus ordering and timestamp of submitted messages.

Until autoRenew functionality is supported by HAPI, the topic will not expire, the autoRenewAccount will not be

charged, and the topic will not automatically be deleted.

Once autoRenew functionality is supported by HAPI:

1. Once the expirationTime is encountered, if an autoRenewAccount is configured on the topic, the account will be

charged automatically at the expirationTime, to extend the expirationTime of the topic up to the topic's

autoRenewPeriod (or as much extension as the account's balance will supply).

2. If the topic expires and is not automatically renewed, the topic will enter the EXPIRED state. All transactions

on the topic will fail with TOPIC_EXPIRED, except an updateTopic() call that modifies only the expirationTime.

getTopicInfo() will succeed. This state will be available for a AUTORENEW_GRACE_PERIOD grace period (7 days).

3. After the grace period, if the topic's expirationTime is not extended, the topic will be automatically

deleted and no transactions or queries on the topic will succeed after that point.

Method NameRequest TypeResponse TypeDescription
createTopic Transaction TransactionResponse

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)

updateTopic Transaction 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)

deleteTopic Transaction 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)

getTopicInfo Query Response

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)

submitMessage Transaction 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)

ConsensusSubmitMessage.proto

Top

ConsensusMessageChunkInfo

FieldTypeLabelDescription
initialTransactionID TransactionID

TransactionID of the first chunk, gets copied to every subsequent chunk in a fragmented message.

total int32

The total number of chunks in the message.

number int32

The sequence number (from 1 to total) of the current chunk in the message.

ConsensusSubmitMessageTransactionBody

FieldTypeLabelDescription
topicID TopicID

Topic to submit message to.

message bytes

Message to be submitted. Max size of the Transaction (including signatures) is 6KiB.

chunkInfo ConsensusMessageChunkInfo

Optional information of the current chunk in a fragmented message.

ConsensusTopicInfo.proto

Top

ConsensusTopicInfo

Current state of a topic.

FieldTypeLabelDescription
memo string

The memo associated with the topic (UTF-8 encoding max 100 bytes)

runningHash bytes

When a topic is created, its running hash is initialized to 48 bytes of binary zeros. For each submitted message, the topic's running hash is then updated to the output of a particular SHA-384 digest whose input data include the previous running hash. See the TransactionReceipt.proto documentation for an exact description of the data included in the SHA-384 digest used for the update.

sequenceNumber uint64

Sequence number (starting at 1 for the first submitMessage) of messages on the topic.

expirationTime Timestamp

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.

adminKey Key

Access control for update/delete of the topic. Null if there is no key.

submitKey Key

Access control for ConsensusService.submitMessage. Null if there is no key.

autoRenewPeriod Duration

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.

autoRenewAccount AccountID

The account, if any, to charge for automatic renewal of the topic's lifetime upon expiry.

ConsensusUpdateTopic.proto

Top

ConsensusUpdateTopicTransactionBody

All fields left null will not be updated.

See [ConsensusService.updateTopic()](#proto.ConsensusService)

FieldTypeLabelDescription
topicID TopicID

memo google.protobuf.StringValue

If set, the new memo to be associated with the topic (UTF-8 encoding max 100 bytes)

expirationTime Timestamp

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.

adminKey Key

Access control for update/delete of the topic. If unspecified, no change. If empty keyList - the adminKey is cleared.

submitKey Key

Access control for ConsensusService.submitMessage. If unspecified, no change. If empty keyList - the submitKey is cleared.

autoRenewPeriod Duration

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.

autoRenewAccount AccountID

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.

ContractCall.proto

Top

ContractCallTransactionBody

FieldTypeLabelDescription
contractID ContractID

the contract instance to call, in the format used in transactions

gas int64

the maximum amount of gas to use for the call

amount int64

number of tinybars sent (the function must be payable if this is nonzero)

functionParameters bytes

which function to call, and the parameters to pass to the function

ContractCallLocal.proto

Top

ContractCallLocalQuery

Call a function of the given smart contract instance, giving it functionParameters as its inputs.

This is performed locally on the particular node that the client is communicating with.

It cannot change the state of the contract instance (and so, cannot spend anything from the instance's cryptocurrency account).

It will not have a consensus timestamp. It cannot generate a record or a receipt. The response will contain the output

returned by the function call. This is useful for calling getter functions, which purely read the state and don't change it.

It is faster and cheaper than a normal call, because it is purely local to a single node.

Unlike a ContractCall transaction, the node will consume the entire amount of provided gas in determining

the fee for this query.

FieldTypeLabelDescription
header QueryHeader

standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither). The payment must cover the fees and all of the gas offered.

contractID ContractID

the contract instance to call, in the format used in transactions

gas int64

The amount of gas to use for the call; all of the gas offered will be used and charged a corresponding fee

functionParameters bytes

which function to call, and the parameters to pass to the function

maxResultSize int64

max number of bytes that the result might include. The run will fail if it would have returned more than this number of bytes.

ContractCallLocalResponse

Response when the client sends the node ContractCallLocalQuery

FieldTypeLabelDescription
header ResponseHeader

standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

functionResult ContractFunctionResult

the value returned by the function (if it completed and didn't fail)

ContractFunctionResult

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.

FieldTypeLabelDescription
contractID ContractID

the smart contract instance whose function was called

contractCallResult bytes

the result returned by the function

errorMessage string

message In case there was an error during smart contract execution

bloom bytes

bloom filter for record

gasUsed uint64

units of gas used to execute contract

logInfo ContractLoginfo repeated

the log info for events returned by the function

createdContractIDs ContractID repeated

the list of smart contracts that were created by the function call

ContractLoginfo

The log information for an event returned by a smart contract function call. One function call may return several such events.

FieldTypeLabelDescription
contractID ContractID

address of a contract that emitted the event

bloom bytes

bloom filter for a particular log

topic bytes repeated

topics of a particular event

data bytes

event data

ContractCreate.proto

Top

ContractCreateTransactionBody

Start a new smart contract instance. After the instance is created, the ContractID for it is in the receipt, and can be

retrieved by the Record or with a GetByKey query. The instance will run the bytecode stored in a previously created

file, referenced either by FileID or by the transaction ID of the transaction that created the file

The constructor will be executed using the given amount of gas, and any unspent gas will be refunded to the paying account. Constructor inputs come from the given constructorParameters.

The instance will exist for autoRenewPeriod seconds. When that is reached, it will renew itself for another autoRenewPeriod seconds by charging its associated cryptocurrency account (which it creates here). If it has insufficient cryptocurrency to extend that long, it will extend as long as it can. If its balance is zero, the instance will be deleted.

A smart contract instance normally enforces rules, so "the code is law". For example, an ERC-20 contract prevents a transfer from being undone without a signature by the recipient of the transfer. This is always enforced if the contract instance was created with the adminKeys being null. But for some uses, it might be desirable to create something like an ERC-20 contract that has a specific group of trusted individuals who can act as a "supreme court" with the ability to override the normal operation, when a sufficient number of them agree to do so. If adminKeys is not null, then they can sign a transaction that can change the state of the smart contract in arbitrary ways, such as to reverse a transaction that violates some standard of behavior that is not covered by the code itself. The admin keys can also be used to change the autoRenewPeriod, and change the adminKeys field itself. The API currently does not implement this ability. But it does allow the adminKeys field to be set and queried, and will in the future implement such admin abilities for any instance that has a non-null adminKeys.

If this constructor stores information, it is charged gas to store it. There is a fee in hbars to maintain that storage until the expiration time, and that fee is added as part of the transaction fee.

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.

FieldTypeLabelDescription
fileID FileID

the file containing the smart contract byte code. A copy will be made and held by the contract instance, and have the same expiration time as the instance. The file is referenced one of two ways:

adminKey Key

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.

gas int64

gas to run the constructor

initialBalance int64

initial number of tinybars to put into the cryptocurrency account associated with and owned by the smart contract

proxyAccountID AccountID

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.

autoRenewPeriod Duration

the instance will charge its account every this many seconds to renew for this long

constructorParameters bytes

parameters to pass to the constructor

shardID ShardID

shard in which to create this

realmID RealmID

realm in which to create this (leave this null to create a new realm)

newRealmAdminKey Key

if realmID is null, then this the admin key for the new realm that will be created

memo string

the memo that was submitted as part of the contract (max 100 bytes)

ContractDelete.proto

Top

ContractDeleteTransactionBody

At consensus, marks a contract as deleted and transfers its remaining hBars, if any, to a designated receiver. After a contract is deleted, it can no longer be called.

If the target contract is immutable (that is, was created without an admin key), then this transaction resolves to MODIFYING_IMMUTABLE_CONTRACT.

--- Signing Requirements ---

1. The admin key of the target contract must sign.

2. If the transfer account or contract has receiverSigRequired, its associated key must also sign.

FieldTypeLabelDescription
contractID ContractID

The id of the contract to be deleted

transferAccountID AccountID

The id of an account to receive any remaining hBars from the deleted contract

transferContractID ContractID

The id of a contract to receive any remaining hBars from the deleted contract

ContractGetBytecode.proto

Top

ContractGetBytecodeQuery

Get the bytecode for a smart contract instance

FieldTypeLabelDescription
header QueryHeader

standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

contractID ContractID

the contract for which information is requested

ContractGetBytecodeResponse

Response when the client sends the node ContractGetBytecodeQuery

FieldTypeLabelDescription
header ResponseHeader

standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

bytecode bytes

the bytecode

ContractGetInfo.proto

Top

ContractGetInfoQuery

Get information about a smart contract instance. This includes the account that it uses, the file containing its bytecode, and the time when it will expire.

FieldTypeLabelDescription
header QueryHeader

standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

contractID ContractID

the contract for which information is requested

ContractGetInfoResponse

Response when the client sends the node ContractGetInfoQuery

FieldTypeLabelDescription
header ResponseHeader

standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

contractInfo ContractGetInfoResponse.ContractInfo

the information about this contract instance (a state proof can be generated for this)

ContractGetInfoResponse.ContractInfo

FieldTypeLabelDescription
contractID ContractID

ID of the contract instance, in the format used in transactions

accountID AccountID

ID of the cryptocurrency account owned by the contract instance, in the format used in transactions

contractAccountID string

ID of both the contract instance and the cryptocurrency account owned by the contract instance, in the format used by Solidity

adminKey Key

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. */

expirationTime Timestamp

the current time at which this contract instance (and its account) is set to expire

autoRenewPeriod Duration

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.

storage int64

number of bytes of storage being used by this instance (which affects the cost to extend the expiration time)

memo string

the memo associated with the contract (max 100 bytes)

balance uint64

The current balance, in tinybars

deleted bool

Whether the contract has been deleted

tokenRelationships TokenRelationship repeated

The tokens associated to the contract

ContractGetRecords.proto

Top

ContractGetRecordsQuery

Before v0.9.0, requested records of all transactions against the given contract in the last 25 hours.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

contractID ContractID

The smart contract instance for which the records should be retrieved

ContractGetRecordsResponse

Before v0.9.0, returned records of all transactions against the given contract in the last 25 hours.

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

contractID ContractID

The smart contract instance that this record is for

records TransactionRecord repeated

List of records, each with contractCreateResult or contractCallResult as its body

ContractUpdate.proto

Top

ContractUpdateTransactionBody

At consensus, updates the fields of a smart contract to the given values.

If no value is given for a field, that field is left unchanged on the contract. For an immutable smart contract (that is, a contract created without an adminKey), only the expirationTime may be updated; setting any other field in this case will cause the transaction status to resolve to MODIFYING_IMMUTABLE_CONTRACT.

--- Signing Requirements ---

1. Whether or not a contract has an admin Key, its expiry can be extended with only the transaction payer's signature.

2. Updating any other field of a mutable contract requires the admin key's signature.

3. If the update transaction includes a new admin key, this new key must also sign unless it is exactly an empty KeyList. This special sentinel key removes the existing admin key and causes the contract to become immutable. (Other Key structures without a constituent Ed25519 key will be rejected with INVALID_ADMIN_KEY.)

FieldTypeLabelDescription
contractID ContractID

The id of the contract to be updated

expirationTime Timestamp

The new expiry of the contract, no earlier than the current expiry (resolves to EXPIRATION_REDUCTION_NOT_ALLOWED otherwise)

adminKey Key

The new key to control updates to the contract

proxyAccountID AccountID

(NOT YET IMPLEMENTED) The new id of the account to which the contract is proxy staked

autoRenewPeriod Duration

(NOT YET IMPLEMENTED) The new interval at which the contract will pay to extend its expiry (by the same interval)

fileID FileID

The new id of the file asserted to contain the bytecode of the Solidity transaction that created this contract

memo string

[Deprecated] If set with a non-zero length, the new memo to be associated with the account (UTF-8 encoding max 100 bytes)

memoWrapper google.protobuf.StringValue

If set, the new memo to be associated with the account (UTF-8 encoding max 100 bytes)

Fields with deprecated option

Name Option
memo

true

CryptoAddLiveHash.proto

Top

CryptoAddLiveHashTransactionBody

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.

FieldTypeLabelDescription
liveHash LiveHash

A hash of some credential or certificate, along with the keys of the entities that asserted it validity

LiveHash

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.

FieldTypeLabelDescription
accountId AccountID

The account to which the livehash is attached

hash bytes

The SHA-384 hash of a credential or certificate

keys KeyList

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.

duration Duration

The duration for which the livehash will remain valid

CryptoCreate.proto

Top

CryptoCreateTransactionBody

Create a new account. After the account is created, the AccountID for it is in the receipt. It can also be retrieved with a GetByKey query. Threshold values can be defined, and records are generated and stored for 25 hours for any transfer that exceeds the thresholds. This account is charged for each record generated, so the thresholds are useful for limiting record generation to happen only for large transactions.

The Key field is the key used to sign transactions for this account. If the account has receiverSigRequired set to true, then all cryptocurrency transfers must be signed by this account's key, both for transfers in and out. If it is false, then only transfers out have to be signed by it. When the account is created, the payer account is charged enough hbars so that the new account will not expire for the next autoRenewPeriod seconds. When it reaches the expiration time, the new account will then be automatically charged to renew for another autoRenewPeriod seconds. If it does not have enough hbars to renew for that long, then the remaining hbars are used to extend its expiration as long as possible. If it is has a zero balance when it expires, then it is deleted. This transaction must be signed by the payer account. If receiverSigRequired is false, then the transaction does not have to be signed by the keys in the keys field. If it is true, then it must be signed by them, in addition to the keys of the payer account.

An entity (account, file, or smart contract instance) must be created in a particular realm. If the realmID is left null, then a new realm will be created with the given admin key. If a new realm has a null adminKey, then anyone can create/modify/delete entities in that realm. But if an admin key is given, then any transaction to create/modify/delete an entity in that realm must be signed by that key, though anyone can still call functions on smart contract instances that exist in that realm. A realm ceases to exist when everything within it has expired and no longer exists.

The current API ignores shardID, realmID, and newRealmAdminKey, and creates everything in shard 0 and realm 0, with a null key. Future versions of the API will support multiple realms and multiple shards.

FieldTypeLabelDescription
key Key

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.

initialBalance uint64

The initial number of tinybars to put into the account

proxyAccountID AccountID

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.

sendRecordThreshold uint64

[Deprecated]. The threshold amount (in tinybars) for which an account record is created for any send/withdraw transaction

receiveRecordThreshold uint64

[Deprecated]. The threshold amount (in tinybars) for which an account record is created for any receive/deposit transaction

receiverSigRequired bool

If true, this account's key must sign any transaction depositing into this account (in addition to all withdrawals)

autoRenewPeriod Duration

The account is charged to extend its expiration date every this many seconds. If it doesn't have enough balance, it extends as long as possible. If it is empty when it expires, then it is deleted.

shardID ShardID

The shard in which this account is created

realmID RealmID

The realm in which this account is created (leave this null to create a new realm)

newRealmAdminKey Key

If realmID is null, then this the admin key for the new realm that will be created

memo string

The memo associated with the account (UTF-8 encoding max 100 bytes)

Fields with deprecated option

Name Option
sendRecordThreshold

true

receiveRecordThreshold

true

CryptoDelete.proto

Top

CryptoDeleteTransactionBody

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.

FieldTypeLabelDescription
transferAccountID AccountID

The account ID which will receive all remaining hbars

deleteAccountID AccountID

The account ID which should be deleted

CryptoDeleteLiveHash.proto

Top

CryptoDeleteLiveHashTransactionBody

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.

FieldTypeLabelDescription
accountOfLiveHash AccountID

The account owning the livehash

liveHashToDelete bytes

The SHA-384 livehash to delete from the account

CryptoGetAccountBalance.proto

Top

CryptoGetAccountBalanceQuery

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.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

accountID AccountID

The account ID for which information is requested

contractID ContractID

The account ID for which information is requested

CryptoGetAccountBalanceResponse

Response when the client sends the node CryptoGetAccountBalanceQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither.

accountID AccountID

The account ID that is being described (this is useful with state proofs, for proving to a third party)

balance uint64

The current balance, in tinybars.

tokenBalances TokenBalance repeated

The token balances possessed by the target account.

CryptoGetAccountRecords.proto

Top

CryptoGetAccountRecordsQuery

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.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

accountID AccountID

The account ID for which the records should be retrieved

CryptoGetAccountRecordsResponse

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.

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

accountID AccountID

The account that this record is for

records TransactionRecord repeated

List of records

CryptoGetInfo.proto

Top

CryptoGetInfoQuery

Get all the information about an account, including the balance. This does not get the list of account records.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

accountID AccountID

The account ID for which information is requested

CryptoGetInfoResponse

Response when the client sends the node CryptoGetInfoQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

accountInfo CryptoGetInfoResponse.AccountInfo

Info about the account (a state proof can be generated for this)

CryptoGetInfoResponse.AccountInfo

FieldTypeLabelDescription
accountID AccountID

The account ID for which this information applies

contractAccountID string

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

deleted bool

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

proxyAccountID AccountID

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.

proxyReceived int64

The total number of tinybars proxy staked to this account

key Key

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.

balance uint64

The current balance of account in tinybars

generateSendRecordThreshold uint64

[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

generateReceiveRecordThreshold uint64

[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

receiverSigRequired bool

If true, no transaction can transfer to this account unless signed by this account's key

expirationTime Timestamp

The TimeStamp time at which this account is set to expire

autoRenewPeriod Duration

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.

liveHashes LiveHash repeated

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)

tokenRelationships TokenRelationship repeated

All tokens related to this account

memo string

The memo associated with the account

Fields with deprecated option

Name Option
generateSendRecordThreshold

true

generateReceiveRecordThreshold

true

CryptoGetLiveHash.proto

Top

CryptoGetLiveHashQuery

Requests a livehash associated to an account.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

accountID AccountID

The account to which the livehash is associated

hash bytes

The SHA-384 data in the livehash

CryptoGetLiveHashResponse

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.

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

liveHash LiveHash

The livehash, if present

CryptoGetStakers.proto

Top

AllProxyStakers

all of the accounts proxy staking to a given account, and the amounts proxy staked

FieldTypeLabelDescription
accountID AccountID

The Account ID that is being proxy staked to

proxyStaker ProxyStaker repeated

Each of the proxy staking accounts, and the amount they are proxy staking

CryptoGetStakersQuery

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.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

accountID AccountID

The Account ID for which the records should be retrieved

CryptoGetStakersResponse

Response when the client sends the node CryptoGetStakersQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

stakers AllProxyStakers

List of accounts proxy staking to this account, and the amount each is currently proxy staking

ProxyStaker

information about a single account that is proxy staking

FieldTypeLabelDescription
accountID AccountID

The Account ID that is proxy staking

amount int64

The number of hbars that are currently proxy staked

CryptoService.proto

Top

CryptoService

Transactions and queries for the Crypto Service

Method NameRequest TypeResponse TypeDescription
createAccount Transaction TransactionResponse

Creates a new account by submitting the transaction

updateAccount Transaction TransactionResponse

Updates an account by submitting the transaction

cryptoTransfer Transaction TransactionResponse

Initiates a transfer by submitting the transaction

cryptoDelete Transaction TransactionResponse

Deletes and account by submitting the transaction

addLiveHash Transaction TransactionResponse

(NOT CURRENTLY SUPPORTED) Adds a livehash

deleteLiveHash Transaction TransactionResponse

(NOT CURRENTLY SUPPORTED) Deletes a livehash

getLiveHash Query Response

(NOT CURRENTLY SUPPORTED) Retrieves a livehash for an account

getAccountRecords Query Response

Returns all transactions in the last 180s of consensus time for which the given account was the effective payer <b>and</b> network property <tt>ledger.keepRecordsInState</tt> was <tt>true</tt>.

cryptoGetBalance Query Response

Retrieves the balance of an account

getAccountInfo Query Response

Retrieves the metadata of an account

getTransactionReceipts Query Response

Retrieves the latest receipt for a transaction that is either awaiting consensus, or reached consensus in the last 180 seconds

getFastTransactionRecord Query Response

(NOT CURRENTLY SUPPORTED) Returns the records of transactions recently funded by an account

getTxRecordByTxID Query Response

Retrieves the record of a transaction that is either awaiting consensus, or reached consensus in the last 180 seconds

getStakersByAccountID Query Response

(NOT CURRENTLY SUPPORTED) Retrieves the stakers for a node by account id

CryptoTransfer.proto

Top

CryptoTransferTransactionBody

Transfer cryptocurrency from some accounts to other accounts. The accounts list can contain up to 10 accounts. The amounts list must be the same length as the accounts list. 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.

FieldTypeLabelDescription
transfers TransferList

tokenTransfers TokenTransferList repeated

CryptoUpdate.proto

Top

CryptoUpdateTransactionBody

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.

FieldTypeLabelDescription
accountIDToUpdate AccountID

The account ID which is being updated in this transaction

key Key

The new key

proxyAccountID AccountID

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.

proxyFraction int32

[Deprecated]. Payments earned from proxy staking are shared between the node and this account, with proxyFraction / 10000 going to this account

sendRecordThreshold uint64

[Deprecated]. The new threshold amount (in tinybars) for which an account record is created for any send/withdraw transaction

sendRecordThresholdWrapper google.protobuf.UInt64Value

[Deprecated]. The new threshold amount (in tinybars) for which an account record is created for any send/withdraw transaction

receiveRecordThreshold uint64

[Deprecated]. The new threshold amount (in tinybars) for which an account record is created for any receive/deposit transaction.

receiveRecordThresholdWrapper google.protobuf.UInt64Value

[Deprecated]. The new threshold amount (in tinybars) for which an account record is created for any receive/deposit transaction.

autoRenewPeriod Duration

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.

expirationTime Timestamp

The new expiration time to extend to (ignored if equal to or before the current one)

receiverSigRequired bool

[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.

receiverSigRequiredWrapper google.protobuf.BoolValue

If true, this account's key must sign any transaction depositing into this account (in addition to all withdrawals)

memo google.protobuf.StringValue

If set, the new memo to be associated with the account (UTF-8 encoding max 100 bytes)

Fields with deprecated option

Name Option
proxyFraction

true

sendRecordThreshold

true

sendRecordThresholdWrapper

true

receiveRecordThreshold

true

receiveRecordThresholdWrapper

true

receiverSigRequired

true

Duration.proto

Top

Duration

A length of time in seconds.

FieldTypeLabelDescription
seconds int64

The number of seconds

ExchangeRate.proto

Top

ExchangeRate

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.

FieldTypeLabelDescription
hbarEquiv int32

Denominator in calculation of exchange rate between hbar and cents

centEquiv int32

Numerator in calculation of exchange rate between hbar and cents

expirationTime TimestampSeconds

Expiration time in seconds for this exchange rate

ExchangeRateSet

Two sets of exchange rates

FieldTypeLabelDescription
currentRate ExchangeRate

Current exchange rate

nextRate ExchangeRate

Next exchange rate which will take effect when current rate expires

FileAppend.proto

Top

FileAppendTransactionBody

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.

FieldTypeLabelDescription
fileID FileID

The file to which the bytes will be appended

contents bytes

The bytes that will be appended to the end of the specified file

FileCreate.proto

Top

FileCreateTransactionBody

Create a new file, containing the given contents.

After the file is created, the FileID for it can be found in the receipt, or record, or retrieved with a GetByKey query.

The file contains the specified contents (possibly empty). The file will automatically disappear at the expirationTime, unless its expiration is extended by another transaction before that time. If the file is deleted, then its contents will become empty and it will be marked as deleted until it expires, and then it will cease to exist.

The keys field is a list of keys. All the keys on the list must sign to create or modify a file, but only one of them needs to sign in order to delete the file. Each of those "keys" may itself be threshold key containing other keys (including other threshold keys). In other words, the behavior is an AND for create/modify, OR for delete. This is useful for acting as a revocation server. If it is desired to have the behavior be AND for all 3 operations (or OR for all 3), then the list should have only a single Key, which is a threshold key, with N=1 for OR, N=M for AND.

If a file is created without ANY keys in the keys field, the file is immutable and ONLY the expirationTime of the file can be changed with a FileUpdate transaction. The file contents or its keys cannot be changed.

An entity (account, file, or smart contract instance) must be created in a particular realm. If the realmID is left null, then a new realm will be created with the given admin key. If a new realm has a null adminKey, then anyone can create/modify/delete entities in that realm. But if an admin key is given, then any transaction to create/modify/delete an entity in that realm must be signed by that key, though anyone can still call functions on smart contract instances that exist in that realm. A realm ceases to exist when everything within it has expired and no longer exists.

The current API ignores shardID, realmID, and newRealmAdminKey, and creates everything in shard 0 and realm 0, with a null key. Future versions of the API will support multiple realms and multiple shards.

FieldTypeLabelDescription
expirationTime Timestamp

The time at which this file should expire (unless FileUpdateTransaction is used before then to extend its life)

keys KeyList

All these keys must sign to create or modify the file. Any one of them can sign to delete the file.

contents bytes

The bytes that are the contents of the file

shardID ShardID

Shard in which this file is created

realmID RealmID

The Realm in which to the file is created (leave this null to create a new realm)

newRealmAdminKey Key

If realmID is null, then this the admin key for the new realm that will be created

memo string

The memo associated with the file (UTF-8 encoding max 100 bytes)

FileDelete.proto

Top

FileDeleteTransactionBody

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 keys on that list must sign transactions to create or modify the file, but any single one of them can be used to delete the file. Each "key" on that list may itself be a threshold key containing other keys (including other threshold keys).

FieldTypeLabelDescription
fileID FileID

The file to delete. It will be marked as deleted until it expires. Then it will disappear.

FileGetContents.proto

Top

FileGetContentsQuery

Get the contents of a file. The content field is empty (no bytes) if the file is empty.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

fileID FileID

The file ID of the file whose contents are requested

FileGetContentsResponse

Response when the client sends the node FileGetContentsQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

fileContents FileGetContentsResponse.FileContents

the file ID and contents (a state proof can be generated for this)

FileGetContentsResponse.FileContents

FieldTypeLabelDescription
fileID FileID

The file ID of the file whose contents are being returned

contents bytes

The bytes contained in the file

FileGetInfo.proto

Top

FileGetInfoQuery

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.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

fileID FileID

The file ID of the file for which information is requested

FileGetInfoResponse

Response when the client sends the node FileGetInfoQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

fileInfo FileGetInfoResponse.FileInfo

The information about the file

FileGetInfoResponse.FileInfo

FieldTypeLabelDescription
fileID FileID

The file ID of the file for which information is requested

size int64

Number of bytes in contents

expirationTime Timestamp

The current time at which this account is set to expire

deleted bool

True if deleted but not yet expired

keys KeyList

One of these keys must sign in order to modify or delete the file

memo string

The memo associated with the file

FileService.proto

Top

FileService

Transactions and queries for the file service.

Method NameRequest TypeResponse TypeDescription
createFile Transaction TransactionResponse

Creates a file

updateFile Transaction TransactionResponse

Updates a file

deleteFile Transaction TransactionResponse

Deletes a file

appendContent Transaction TransactionResponse

Appends to a file

getFileContent Query Response

Retrieves the file contents

getFileInfo Query Response

Retrieves the file information

systemDelete Transaction TransactionResponse

Deletes a file if the submitting account has network admin privileges

systemUndelete Transaction TransactionResponse

Undeletes a file if the submitting account has network admin privileges

FileUpdate.proto

Top

FileUpdateTransactionBody

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 key list of the file being updated. If the keys themselves are being update, then the transaction must also be signed by all the new keys.

FieldTypeLabelDescription
fileID FileID

The ID of the file to update

expirationTime Timestamp

The new expiry time (ignored if not later than the current expiry)

keys KeyList

The new list of keys that can modify or delete the file

contents bytes

The new contents that should overwrite the file's current contents

memo google.protobuf.StringValue

If set, the new memo to be associated with the file (UTF-8 encoding max 100 bytes)

Freeze.proto

Top

FreezeTransactionBody

Set the freezing period in which the platform will stop creating events and accepting transactions. This is used before safely shut down the platform for maintenance.

FieldTypeLabelDescription
startHour int32

The start hour (in UTC time), a value between 0 and 23

startMin int32

The start minute (in UTC time), a value between 0 and 59

endHour int32

The end hour (in UTC time), a value between 0 and 23

endMin int32

The end minute (in UTC time), a value between 0 and 59

updateFile FileID

The ID of the file needs to be updated during a freeze transaction

fileHash bytes

The hash value of the file, used to verify file content before performing freeze and update

FreezeService.proto

Top

FreezeService

The request and responses for freeze service.

Method NameRequest TypeResponse TypeDescription
freeze Transaction TransactionResponse

Freezes the nodes by submitting the transaction. The grpc server returns the TransactionResponse

GetByKey.proto

Top

EntityID

the ID for a single entity (account, livehash, file, or smart contract instance)

FieldTypeLabelDescription
accountID AccountID

The Account ID for the cryptocurrency account

liveHash LiveHash

A uniquely identifying livehash of an acount

fileID FileID

The file ID of the file

contractID ContractID

The smart contract ID that identifies instance

GetByKeyQuery

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.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

key Key

The key to search for. It must not contain a contractID nor a ThresholdSignature.

GetByKeyResponse

Response when the client sends the node GetByKeyQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

entities EntityID repeated

The list of entities that include this public key in their associated Key list

GetBySolidityID.proto

Top

GetBySolidityIDQuery

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.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

solidityID string

The ID in the format used by Solidity

GetBySolidityIDResponse

Response when the client sends the node GetBySolidityIDQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

accountID AccountID

The Account ID for the cryptocurrency account

fileID FileID

The file Id for the file

contractID ContractID

A smart contract ID for the instance (if this is included, then the associated accountID will also be included)

NetworkGetVersionInfo.proto

Top

NetworkGetVersionInfoQuery

Get the deployed versions of Hedera Services and the HAPI proto in semantic version format

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

NetworkGetVersionInfoResponse

Response when the client sends the node NetworkGetVersionInfoQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

hapiProtoVersion SemanticVersion

The Hedera API (HAPI) protobuf version recognized by the responding node.

hederaServicesVersion SemanticVersion

The version of the Hedera Services software deployed on the responding node.

NetworkService.proto

Top

NetworkService

The requests and responses for different network services.

Method NameRequest TypeResponse TypeDescription
getVersionInfo Query Response

Retrieves the active versions of Hedera Services and HAPI proto

uncheckedSubmit Transaction TransactionResponse

Submits a "wrapped" transaction to the network, skipping its standard prechecks. (Note that the "wrapper" <tt>UncheckedSubmit</tt> transaction is still subject to normal prechecks, including an authorization requirement that its payer be either the treasury or system admin account.)

Query.proto

Top

Query

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.

FieldTypeLabelDescription
getByKey GetByKeyQuery

Get all entities associated with a given key

getBySolidityID GetBySolidityIDQuery

Get the IDs in the format used in transactions, given the format used in Solidity

contractCallLocal ContractCallLocalQuery

Call a function of a smart contract instance

contractGetInfo ContractGetInfoQuery

Get information about a smart contract instance

contractGetBytecode ContractGetBytecodeQuery

Get bytecode used by a smart contract instance

ContractGetRecords ContractGetRecordsQuery

Get Records of the contract instance

cryptogetAccountBalance CryptoGetAccountBalanceQuery

Get the current balance in a cryptocurrency account

cryptoGetAccountRecords CryptoGetAccountRecordsQuery

Get all the records that currently exist for transactions involving an account

cryptoGetInfo CryptoGetInfoQuery

Get all information about an account

cryptoGetLiveHash CryptoGetLiveHashQuery

Get a single livehash from a single account, if present

cryptoGetProxyStakers CryptoGetStakersQuery

Get all the accounts that proxy stake to a given account, and how much they proxy stake (not yet implemented in the current API)

fileGetContents FileGetContentsQuery

Get the contents of a file (the bytes stored in it)

fileGetInfo FileGetInfoQuery

Get information about a file, such as its expiration date

transactionGetReceipt TransactionGetReceiptQuery

Get a receipt for a transaction (lasts 180 seconds)

transactionGetRecord TransactionGetRecordQuery

Get a record for a transaction

transactionGetFastRecord TransactionGetFastRecordQuery

Get a record for a transaction (lasts 180 seconds)

consensusGetTopicInfo ConsensusGetTopicInfoQuery

Get the parameters of and state of a consensus topic.

networkGetVersionInfo NetworkGetVersionInfoQuery

Get the versions of the HAPI protobuf and Hedera Services software deployed on the responding node.

tokenGetInfo TokenGetInfoQuery

Get all information about a token

scheduleGetInfo ScheduleGetInfoQuery

Get all information about a scheduled entity

QueryHeader.proto

Top

QueryHeader

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.

FieldTypeLabelDescription
payment Transaction

A signed CryptoTransferTransaction to pay the node a fee for handling this query

responseType ResponseType

The requested response, asking for cost, state proof, both, or neither

ResponseType

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.

NameNumberDescription
ANSWER_ONLY 0

Response returns answer

ANSWER_STATE_PROOF 1

(NOT YET SUPPORTED) Response returns both answer and state proof

COST_ANSWER 2

Response returns the cost of answer

COST_ANSWER_STATE_PROOF 3

(NOT YET SUPPORTED) Response returns the total cost of answer and state proof

Response.proto

Top

Response

A single response, which is returned from the node to the client, after the client sent the node a query. This includes all responses.

FieldTypeLabelDescription
getByKey GetByKeyResponse

Get all entities associated with a given key

getBySolidityID GetBySolidityIDResponse

Get the IDs in the format used in transactions, given the format used in Solidity

contractCallLocal ContractCallLocalResponse

Response to call a function of a smart contract instance

contractGetBytecodeResponse ContractGetBytecodeResponse

Get the bytecode for a smart contract instance

contractGetInfo ContractGetInfoResponse

Get information about a smart contract instance

contractGetRecordsResponse ContractGetRecordsResponse

Get all existing records for a smart contract instance

cryptogetAccountBalance CryptoGetAccountBalanceResponse

Get the current balance in a cryptocurrency account

cryptoGetAccountRecords CryptoGetAccountRecordsResponse

Get all the records that currently exist for transactions involving an account

cryptoGetInfo CryptoGetInfoResponse

Get all information about an account

cryptoGetLiveHash CryptoGetLiveHashResponse

Contains a livehash associated to an account

cryptoGetProxyStakers CryptoGetStakersResponse

Get all the accounts that proxy stake to a given account, and how much they proxy stake

fileGetContents FileGetContentsResponse

Get the contents of a file (the bytes stored in it)

fileGetInfo FileGetInfoResponse

Get information about a file, such as its expiration date

transactionGetReceipt TransactionGetReceiptResponse

Get a receipt for a transaction

transactionGetRecord TransactionGetRecordResponse

Get a record for a transaction

transactionGetFastRecord TransactionGetFastRecordResponse

Get a record for a transaction (lasts 180 seconds)

consensusGetTopicInfo ConsensusGetTopicInfoResponse

Parameters of and state of a consensus topic..

networkGetVersionInfo NetworkGetVersionInfoResponse

Semantic versions of Hedera Services and HAPI proto

tokenGetInfo TokenGetInfoResponse

Get all information about a token

scheduleGetInfo ScheduleGetInfoResponse

Get all information about a schedule entity

ResponseCode.proto

Top

ResponseCodeEnum

NameNumberDescription
OK 0

The transaction passed the precheck validations.

INVALID_TRANSACTION 1

For any error not handled by specific error codes listed below.

PAYER_ACCOUNT_NOT_FOUND 2

Payer account does not exist.

INVALID_NODE_ACCOUNT 3

Node Account provided does not match the node account of the node the transaction was submitted to.

TRANSACTION_EXPIRED 4

Pre-Check error when TransactionValidStart + transactionValidDuration is less than current consensus time.

INVALID_TRANSACTION_START 5

Transaction start time is greater than current consensus time

INVALID_TRANSACTION_DURATION 6

valid transaction duration is a positive non zero number that does not exceed 120 seconds

INVALID_SIGNATURE 7

The transaction signature is not valid

MEMO_TOO_LONG 8

Transaction memo size exceeded 100 bytes

INSUFFICIENT_TX_FEE 9

The fee provided in the transaction is insufficient for this type of transaction

INSUFFICIENT_PAYER_BALANCE 10

The payer account has insufficient cryptocurrency to pay the transaction fee

DUPLICATE_TRANSACTION 11

This transaction ID is a duplicate of one that was submitted to this node or reached consensus in the last 180 seconds (receipt period)

BUSY 12

If API is throttled out

NOT_SUPPORTED 13

The API is not currently supported

INVALID_FILE_ID 14

The file id is invalid or does not exist

INVALID_ACCOUNT_ID 15

The account id is invalid or does not exist

INVALID_CONTRACT_ID 16

The contract id is invalid or does not exist

INVALID_TRANSACTION_ID 17

Transaction id is not valid

RECEIPT_NOT_FOUND 18

Receipt for given transaction id does not exist

RECORD_NOT_FOUND 19

Record for given transaction id does not exist

INVALID_SOLIDITY_ID 20

The solidity id is invalid or entity with this solidity id does not exist

UNKNOWN 21

The responding node has submitted the transaction to the network. Its final status is still unknown.

SUCCESS 22

The transaction succeeded

FAIL_INVALID 23

There was a system error and the transaction failed because of invalid request parameters.

FAIL_FEE 24

There was a system error while performing fee calculation, reserved for future.

FAIL_BALANCE 25

There was a system error while performing balance checks, reserved for future.

KEY_REQUIRED 26

Key not provided in the transaction body

BAD_ENCODING 27

Unsupported algorithm/encoding used for keys in the transaction

INSUFFICIENT_ACCOUNT_BALANCE 28

When the account balance is not sufficient for the transfer

INVALID_SOLIDITY_ADDRESS 29

During an update transaction when the system is not able to find the Users Solidity address

INSUFFICIENT_GAS 30

Not enough gas was supplied to execute transaction

CONTRACT_SIZE_LIMIT_EXCEEDED 31

contract byte code size is over the limit

LOCAL_CALL_MODIFICATION_EXCEPTION 32

local execution (query) is requested for a function which changes state

CONTRACT_REVERT_EXECUTED 33

Contract REVERT OPCODE executed

CONTRACT_EXECUTION_EXCEPTION 34

For any contract execution related error not handled by specific error codes listed above.

INVALID_RECEIVING_NODE_ACCOUNT 35

In Query validation, account with +ve(amount) value should be Receiving node account, the receiver account should be only one account in the list

MISSING_QUERY_HEADER 36

Header is missing in Query request

ACCOUNT_UPDATE_FAILED 37

The update of the account failed

INVALID_KEY_ENCODING 38

Provided key encoding was not supported by the system

NULL_SOLIDITY_ADDRESS 39

null solidity address

CONTRACT_UPDATE_FAILED 40

update of the contract failed

INVALID_QUERY_HEADER 41

the query header is invalid

INVALID_FEE_SUBMITTED 42

Invalid fee submitted

INVALID_PAYER_SIGNATURE 43

Payer signature is invalid

KEY_NOT_PROVIDED 44

The keys were not provided in the request.

INVALID_EXPIRATION_TIME 45

Expiration time provided in the transaction was invalid.

NO_WACL_KEY 46

WriteAccess Control Keys are not provided for the file

FILE_CONTENT_EMPTY 47

The contents of file are provided as empty.

INVALID_ACCOUNT_AMOUNTS 48

The crypto transfer credit and debit do not sum equal to 0

EMPTY_TRANSACTION_BODY 49

Transaction body provided is empty

INVALID_TRANSACTION_BODY 50

Invalid transaction body provided

INVALID_SIGNATURE_TYPE_MISMATCHING_KEY 51

the type of key (base ed25519 key, KeyList, or ThresholdKey) does not match the type of signature (base ed25519 signature, SignatureList, or ThresholdKeySignature)

INVALID_SIGNATURE_COUNT_MISMATCHING_KEY 52

the number of key (KeyList, or ThresholdKey) does not match that of signature (SignatureList, or ThresholdKeySignature). e.g. if a keyList has 3 base keys, then the corresponding signatureList should also have 3 base signatures.

EMPTY_LIVE_HASH_BODY 53

the livehash body is empty

EMPTY_LIVE_HASH 54

the livehash data is missing

EMPTY_LIVE_HASH_KEYS 55

the keys for a livehash are missing

INVALID_LIVE_HASH_SIZE 56

the livehash data is not the output of a SHA-384 digest

EMPTY_QUERY_BODY 57

the query body is empty

EMPTY_LIVE_HASH_QUERY 58

the crypto livehash query is empty

LIVE_HASH_NOT_FOUND 59

the livehash is not present

ACCOUNT_ID_DOES_NOT_EXIST 60

the account id passed has not yet been created.

LIVE_HASH_ALREADY_EXISTS 61

the livehash already exists for a given account

INVALID_FILE_WACL 62

File WACL keys are invalid

SERIALIZATION_FAILED 63

Serialization failure

TRANSACTION_OVERSIZE 64

The size of the Transaction is greater than transactionMaxBytes

TRANSACTION_TOO_MANY_LAYERS 65

The Transaction has more than 50 levels

CONTRACT_DELETED 66

Contract is marked as deleted

PLATFORM_NOT_ACTIVE 67

the platform node is either disconnected or lagging behind.

KEY_PREFIX_MISMATCH 68

one public key matches more than one prefixes on the signature map

PLATFORM_TRANSACTION_NOT_CREATED 69

transaction not created by platform due to large backlog

INVALID_RENEWAL_PERIOD 70

auto renewal period is not a positive number of seconds

INVALID_PAYER_ACCOUNT_ID 71

the response code when a smart contract id is passed for a crypto API request

ACCOUNT_DELETED 72

the account has been marked as deleted

FILE_DELETED 73

the file has been marked as deleted

ACCOUNT_REPEATED_IN_ACCOUNT_AMOUNTS 74

same accounts repeated in the transfer account list

SETTING_NEGATIVE_ACCOUNT_BALANCE 75

attempting to set negative balance value for crypto account

OBTAINER_REQUIRED 76

when deleting smart contract that has crypto balance either transfer account or transfer smart contract is required

OBTAINER_SAME_CONTRACT_ID 77

when deleting smart contract that has crypto balance you can not use the same contract id as transferContractId as the one being deleted

OBTAINER_DOES_NOT_EXIST 78

transferAccountId or transferContractId specified for contract delete does not exist

MODIFYING_IMMUTABLE_CONTRACT 79

attempting to modify (update or delete a immutable smart contract, i.e. one created without a admin key)

FILE_SYSTEM_EXCEPTION 80

Unexpected exception thrown by file system functions

AUTORENEW_DURATION_NOT_IN_RANGE 81

the duration is not a subset of [MINIMUM_AUTORENEW_DURATION,MAXIMUM_AUTORENEW_DURATION]

ERROR_DECODING_BYTESTRING 82

Decoding the smart contract binary to a byte array failed. Check that the input is a valid hex string.

CONTRACT_FILE_EMPTY 83

File to create a smart contract was of length zero

CONTRACT_BYTECODE_EMPTY 84

Bytecode for smart contract is of length zero

INVALID_INITIAL_BALANCE 85

Attempt to set negative initial balance

INVALID_RECEIVE_RECORD_THRESHOLD 86

[Deprecated]. attempt to set negative receive record threshold

INVALID_SEND_RECORD_THRESHOLD 87

[Deprecated]. attempt to set negative send record threshold

ACCOUNT_IS_NOT_GENESIS_ACCOUNT 88

Special Account Operations should be performed by only Genesis account, return this code if it is not Genesis Account

PAYER_ACCOUNT_UNAUTHORIZED 89

The fee payer account doesn't have permission to submit such Transaction

INVALID_FREEZE_TRANSACTION_BODY 90

FreezeTransactionBody is invalid

FREEZE_TRANSACTION_BODY_NOT_FOUND 91

FreezeTransactionBody does not exist

TRANSFER_LIST_SIZE_LIMIT_EXCEEDED 92

Exceeded the number of accounts (both from and to) allowed for crypto transfer list

RESULT_SIZE_LIMIT_EXCEEDED 93

Smart contract result size greater than specified maxResultSize

NOT_SPECIAL_ACCOUNT 94

The payer account is not a special account(account 0.0.55)

CONTRACT_NEGATIVE_GAS 95

Negative gas was offered in smart contract call

CONTRACT_NEGATIVE_VALUE 96

Negative value / initial balance was specified in a smart contract call / create

INVALID_FEE_FILE 97

Failed to update fee file

INVALID_EXCHANGE_RATE_FILE 98

Failed to update exchange rate file

INSUFFICIENT_LOCAL_CALL_GAS 99

Payment tendered for contract local call cannot cover both the fee and the gas

ENTITY_NOT_ALLOWED_TO_DELETE 100

Entities with Entity ID below 1000 are not allowed to be deleted

AUTHORIZATION_FAILED 101

Violating one of these rules: 1) treasury account can update all entities below 0.0.1000, 2) account 0.0.50 can update all entities from 0.0.51 - 0.0.80, 3) Network Function Master Account A/c 0.0.50 - Update all Network Function accounts & perform all the Network Functions listed below, 4) Network Function Accounts: i) A/c 0.0.55 - Update Address Book files (0.0.101/102), ii) A/c 0.0.56 - Update Fee schedule (0.0.111), iii) A/c 0.0.57 - Update Exchange Rate (0.0.112).

FILE_UPLOADED_PROTO_INVALID 102

Fee Schedule Proto uploaded but not valid (append or update is required)

FILE_UPLOADED_PROTO_NOT_SAVED_TO_DISK 103

Fee Schedule Proto uploaded but not valid (append or update is required)

FEE_SCHEDULE_FILE_PART_UPLOADED 104

Fee Schedule Proto File Part uploaded

EXCHANGE_RATE_CHANGE_LIMIT_EXCEEDED 105

The change on Exchange Rate exceeds Exchange_Rate_Allowed_Percentage

MAX_CONTRACT_STORAGE_EXCEEDED 106

Contract permanent storage exceeded the currently allowable limit

TRANSFER_ACCOUNT_SAME_AS_DELETE_ACCOUNT 107

Transfer Account should not be same as Account to be deleted

TOTAL_LEDGER_BALANCE_INVALID 108

EXPIRATION_REDUCTION_NOT_ALLOWED 110

The expiration date/time on a smart contract may not be reduced

MAX_GAS_LIMIT_EXCEEDED 111

Gas exceeded currently allowable gas limit per transaction

MAX_FILE_SIZE_EXCEEDED 112

File size exceeded the currently allowable limit

INVALID_TOPIC_ID 150

The Topic ID specified is not in the system.

INVALID_ADMIN_KEY 155

A provided admin key was invalid.

INVALID_SUBMIT_KEY 156

A provided submit key was invalid.

UNAUTHORIZED 157

An attempted operation was not authorized (ie - a deleteTopic for a topic with no adminKey).

INVALID_TOPIC_MESSAGE 158

A ConsensusService message is empty.

INVALID_AUTORENEW_ACCOUNT 159

The autoRenewAccount specified is not a valid, active account.

AUTORENEW_ACCOUNT_NOT_ALLOWED 160

An adminKey was not specified on the topic, so there must not be an autoRenewAccount.

TOPIC_EXPIRED 162

The topic has expired, was not automatically renewed, and is in a 7 day grace period before the topic will be deleted unrecoverably. This error response code will not be returned until autoRenew functionality is supported by HAPI.

INVALID_CHUNK_NUMBER 163

chunk number must be from 1 to total (chunks) inclusive.

INVALID_CHUNK_TRANSACTION_ID 164

For every chunk, the payer account that is part of initialTransactionID must match the Payer Account of this transaction. The entire initialTransactionID should match the transactionID of the first chunk, but this is not checked or enforced by Hedera except when the chunk number is 1.

ACCOUNT_FROZEN_FOR_TOKEN 165

Account is frozen and cannot transact with the token

TOKENS_PER_ACCOUNT_LIMIT_EXCEEDED 166

An involved account already has more than <tt>tokens.maxPerAccount</tt> associations with non-deleted tokens.

INVALID_TOKEN_ID 167

The token is invalid or does not exist

INVALID_TOKEN_DECIMALS 168

Invalid token decimals

INVALID_TOKEN_INITIAL_SUPPLY 169

Invalid token initial supply

INVALID_TREASURY_ACCOUNT_FOR_TOKEN 170

Treasury Account does not exist or is deleted

INVALID_TOKEN_SYMBOL 171

Token Symbol is not UTF-8 capitalized alphabetical string

TOKEN_HAS_NO_FREEZE_KEY 172

Freeze key is not set on token

TRANSFERS_NOT_ZERO_SUM_FOR_TOKEN 173

Amounts in transfer list are not net zero

MISSING_TOKEN_SYMBOL 174

A token symbol was not provided

TOKEN_SYMBOL_TOO_LONG 175

The provided token symbol was too long

ACCOUNT_KYC_NOT_GRANTED_FOR_TOKEN 176

KYC must be granted and account does not have KYC granted

TOKEN_HAS_NO_KYC_KEY 177

KYC key is not set on token

INSUFFICIENT_TOKEN_BALANCE 178

Token balance is not sufficient for the transaction

TOKEN_WAS_DELETED 179

Token transactions cannot be executed on deleted token

TOKEN_HAS_NO_SUPPLY_KEY 180

Supply key is not set on token

TOKEN_HAS_NO_WIPE_KEY 181

Wipe key is not set on token

INVALID_TOKEN_MINT_AMOUNT 182

The requested token mint amount would cause an invalid total supply

INVALID_TOKEN_BURN_AMOUNT 183

The requested token burn amount would cause an invalid total supply

TOKEN_NOT_ASSOCIATED_TO_ACCOUNT 184

A required token-account relationship is missing

CANNOT_WIPE_TOKEN_TREASURY_ACCOUNT 185

The target of a wipe operation was the token treasury account

INVALID_KYC_KEY 186

The provided KYC key was invalid.

INVALID_WIPE_KEY 187

The provided wipe key was invalid.

INVALID_FREEZE_KEY 188

The provided freeze key was invalid.

INVALID_SUPPLY_KEY 189

The provided supply key was invalid.

MISSING_TOKEN_NAME 190

Token Name is not provided

TOKEN_NAME_TOO_LONG 191

Token Name is too long

INVALID_WIPING_AMOUNT 192

The provided wipe amount must not be negative, zero or bigger than the token holder balance

TOKEN_IS_IMMUTABLE 193

Token does not have Admin key set, thus update/delete transactions cannot be performed

TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT 194

An <tt>associateToken</tt> operation specified a token already associated to the account

TRANSACTION_REQUIRES_ZERO_TOKEN_BALANCES 195

An attempted operation is invalid until all token balances for the target account are zero

ACCOUNT_IS_TREASURY 196

An attempted operation is invalid because the account is a treasury

TOKEN_ID_REPEATED_IN_TOKEN_LIST 197

Same TokenIDs present in the token list

TOKEN_TRANSFER_LIST_SIZE_LIMIT_EXCEEDED 198

Exceeded the number of token transfers (both from and to) allowed for token transfer list

EMPTY_TOKEN_TRANSFER_BODY 199

TokenTransfersTransactionBody has no TokenTransferList

EMPTY_TOKEN_TRANSFER_ACCOUNT_AMOUNTS 200

TokenTransfersTransactionBody has a TokenTransferList with no AccountAmounts

INVALID_SCHEDULE_ID 201

The Scheduled entity does not exist; or has now expired, been deleted, or been executed

SCHEDULE_IS_IMMUTABLE 202

The Scheduled entity cannot be modified. Admin key not set

INVALID_SCHEDULE_PAYER_ID 203

The provided Scheduled Payer does not exist

INVALID_SCHEDULE_ACCOUNT_ID 204

The Schedule Create Transaction TransactionID account does not exist

NO_NEW_VALID_SIGNATURES 205

The provided sig map did not contain any new valid signatures from required signers of the scheduled transaction

UNRESOLVABLE_REQUIRED_SIGNERS 206

The required signers for a scheduled transaction cannot be resolved, for example because they do not exist or have been deleted

UNPARSEABLE_SCHEDULED_TRANSACTION 207

The bytes allegedly representing a transaction to be scheduled could not be parsed

UNSCHEDULABLE_TRANSACTION 208

ScheduleCreate and ScheduleSign transactions cannot be scheduled

SOME_SIGNATURES_WERE_INVALID 209

At least one of the signatures in the provided sig map did not represent a valid signature for any required signer

TRANSACTION_ID_FIELD_NOT_ALLOWED 210

The <tt>scheduled</tt> and <tt>nonce</tt> fields in the <tt>TransactionID</tt> may not be set in a top-level transaction

ResponseHeader.proto

Top

ResponseHeader

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.

FieldTypeLabelDescription
nodeTransactionPrecheckCode ResponseCodeEnum

Result of fee transaction precheck, saying it passed, or why it failed

responseType ResponseType

The requested response is repeated back here, for convenience

cost uint64

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)

stateProof bytes

The state proof for this information (if a state proof was requested, and is available)

ScheduleCreate.proto

Top

ScheduleCreateTransactionBody

Create a new Scheduled Transaction. After the Scheduled Transaction is created, the Schedule ID for it is set in the receipt.

Users are able to create the Scheduled Transactions without the need for them to sign the scheduled underlying transaction (f.e Account A creates Scheduled Transaction for Account B, C and D to sign)

Creating immutable scheduled transaction: Scheduled Transaction can be created as immutable if the adminKey is omitted. In this case no one is able to execute ScheduleDelete operation and the Scheduled Transaction will either execute or expire

Defining the Payer of the Transactions: By default, the payer of the Scheduled Transaction is the Account that creates it in the first place. However, users have the option to create Scheduled Transactions with Payer set to any account. If a Payer is provided, its signature will be required in order for the scheduled transaction to reach execution.

Providing Signatures as part of the creation: Users are able to provide signatures for the Scheduled Transaction as part of the creation itself

Idempotent Creation: Creating Scheduled Transactions is an idempotent operation in the sense that if multiple parties perform ScheduleCreate operation specifying identical transactions, only the first one will create the transaction and the other operations will append the provided signatures.

The criteria for identical transactions is the following: If there is a previously created Scheduled Transaction, that hasn't yet been executed and all of the properties are exactly the same except for the sigMap (transactionBody, adminKey, payerAccountID and memo).

In that sense, ScheduleCreate transaction referring to an already created Scheduled Transaction and providing the rest of the required signature(s) will cause the underlying encoded transaction to be executed!

Note: Even though only the first ScheduleCreate Transaction will create new Scheduled Entity and the rest of them will have their signatures from the sigMap witnessed, the ScheduleID property in the TransactionReceipt will be set on all of them.

INVALID_ACCOUNT_ID is returned if the specified payerAccountID does not exist.

UNRESOLVABLE_REQUIRED_SIGNERS is returned if the transactionBody defines required Signers that cannot be resolved (f.e signature from non-existing account is requested)

UNPARSEABLE_SCHEDULED_TRANSACTION is returned if the transactionBody cannot be parsed into normal Transaction

UNSCHEDULABLE_TRANSACTION is returned if the transactionBody is representing a transaction that is not allowed to be scheduled (f.e scheduling a ScheduleCreate transaction)

SOME_SIGNATURES_WERE_INVALID is returned if one of the signatures provided does not represent a valid signature for any required signer

FieldTypeLabelDescription
transactionBody bytes

The transaction serialized into bytes that must be signed

adminKey Key

(optional) The Key which is able to delete the Scheduled Transaction (if tx is not already executed)

payerAccountID AccountID

(optional) The account which is going to pay for the execution of the Scheduled TX. If not populated, the scheduling account is charged

sigMap SignatureMap

(optional) Signatures that could be provided (similarly to how signatures are provided in ScheduleSign operation) on Scheduled Transaction creation

memo string

(optional) Publicly visible information about the Scheduled entity, up to 100 bytes. No guarantee of uniqueness.

ScheduleDelete.proto

Top

ScheduleDeleteTransactionBody

Deletes a Scheduled Transaction from the ledger.

The operation must be signed by the specified Admin Key of the Scheduled Transaction. If admin key is not set, Transaction will result in SCHEDULE_IS_IMMUTABLE.

Once deleted, sign and delete transactions will resolve to INVALID_SCHEDULE_ID.

FieldTypeLabelDescription
scheduleID ScheduleID

The ID of the Scheduled Entity

ScheduleGetInfo.proto

Top

ScheduleGetInfoQuery

Gets information about Scheduled Transaction instance

Answered with status INVALID_SCHEDULE_ID if the Scheduled Transaction is deleted, expires or is executed.

FieldTypeLabelDescription
header QueryHeader

standard info sent from client to node including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

scheduleID ScheduleID

The ID of the Scheduled Entity

ScheduleGetInfoResponse

Response that gets returned, when the client sends the node a ScheduleGetInfoQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

scheduleInfo ScheduleInfo

The information requested about this schedule instance

ScheduleInfo

Metadata about a Scheduled Transaction instance

FieldTypeLabelDescription
scheduleID ScheduleID

The ID of the Scheduled Entity

creatorAccountID AccountID

The Account ID which created the Scheduled TX

payerAccountID AccountID

The account which is going to pay for the execution of the Scheduled TX

transactionBody bytes

The transaction serialized into bytes that must be signed

signatories KeyList

The signatories that have provided signatures so far for the Scheduled TX

adminKey Key

The Key which is able to delete the Scheduled Transaction if set

memo string

Publicly visible information about the Scheduled entity, up to 100 bytes. No guarantee of uniqueness.

expirationTime Timestamp

The epoch second at which the schedule will expire

ScheduleService.proto

Top

ScheduleService

Transactions and queries for the Schedule Service

The Schedule Service allows transactions to be submitted without all the required signatures and allows anyone to provide the required signatures independently after a transaction has already been created.

Execution:

Scheduled Transactions are executed once all required signatures are collected and witnessed. Every time new signature is provided, a check is performed on the "readiness" of the execution.

The Scheduled Transaction will be executed immediately after the transaction that triggered it and will be externalised in a separate Transaction Record.

Transaction Record:

The timestamp of the Scheduled Transaction will be equal to consensusTimestamp + 1 nano, where consensusTimestamp is the timestamp of the transaction that triggered the execution.

The Transaction ID of the Scheduled Transaction will have the scheduled property set to true and inherit the transactionValidStart and accountID from the ScheduleCreate transaction.

The scheduleRef property of the transaction record will be populated with the ScheduleID of the Scheduled Transaction.

Post execution:

Once a given Scheduled Transaction executes, it will be removed from the ledger and any upcoming operation referring the ScheduleID will resolve to INVALID_SCHEDULE_ID.

Expiry:

Scheduled Transactions have a global expiry time txExpiryTimeSecs (Currently set to 30 minutes). If txExpiryTimeSecs pass and the Scheduled Transaction haven't yet executed, it will be removed from the ledger as if ScheduleDelete operation is executed.

Method NameRequest TypeResponse TypeDescription
createSchedule Transaction TransactionResponse

Creates a new Schedule by submitting the transaction

signSchedule Transaction TransactionResponse

Signs a new Schedule by submitting the transaction

deleteSchedule Transaction TransactionResponse

Deletes a new Schedule by submitting the transaction

getScheduleInfo Query Response

Retrieves the metadata of a schedule entity

ScheduleSign.proto

Top

ScheduleSignTransactionBody

Provides signatures for a given Scheduled Transaction. The Scheduled Transaction executes if all of the required signatures are witnessed.

INVALID_SCHEDULE_ID is returned if the specified ScheduleID does not exist; or has now expired, been deleted, or been executed

UNRESOLVABLE_REQUIRED_SIGNERS is returned if any of the required keys were updated/deleted and cannot be resolved

INVALID_ACCOUNT_ID is returned if the payerAccountID has been deleted or cannot be resolved

NO_NEW_VALID_SIGNATURES is returned if there are no new signatures provided in the sigMap to be witnessed

SOME_SIGNATURES_WERE_INVALID is returned if one of the signatures provided does not represent a valid signature for any required signer

FieldTypeLabelDescription
scheduleID ScheduleID

The ID of the Scheduled entity

sigMap SignatureMap

The signature map containing the signature(s) to authorise the transaction

SmartContractService.proto

Top

SmartContractService

Transactions and queries for the file service.

Method NameRequest TypeResponse TypeDescription
createContract Transaction TransactionResponse

Creates a contract

updateContract Transaction TransactionResponse

Updates a contract with the content

contractCallMethod Transaction TransactionResponse

Calls a contract

getContractInfo Query Response

Retrieves the contract information

contractCallLocalMethod Query Response

Calls a smart contract to be run on a single node

ContractGetBytecode Query Response

Retrieves the byte code of a contract

getBySolidityID Query Response

Retrieves a contract by its Solidity address

getTxRecordByContractID Query Response

Always returns an empty record list, as contract accounts are never effective payers for transactions

deleteContract Transaction TransactionResponse

Deletes a contract instance and transfers any remaining hbars to a specified receiver

systemDelete Transaction TransactionResponse

Deletes a contract if the submitting account has network admin privileges

systemUndelete Transaction TransactionResponse

Undeletes a contract if the submitting account has network admin privileges

Methods with deprecated option

Method Name Option
getTxRecordByContractID

true

SystemDelete.proto

Top

SystemDeleteTransactionBody

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.

FieldTypeLabelDescription
fileID FileID

The file ID of the file to delete, in the format used in transactions

contractID ContractID

The contract ID instance to delete, in the format used in transactions

expirationTime TimestampSeconds

The timestamp in seconds at which the "deleted" file should truly be permanently deleted

SystemUndelete.proto

Top

SystemUndeleteTransactionBody

Undelete a file or smart contract that was deleted by SystemDelete; requires a Hedera administrative multisignature.

FieldTypeLabelDescription
fileID FileID

The file ID to undelete, in the format used in transactions

contractID ContractID

The contract ID instance to undelete, in the format used in transactions

Timestamp.proto

Top

Timestamp

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)

FieldTypeLabelDescription
seconds int64

Number of complete seconds since the start of the epoch

nanos int32

Number of nanoseconds since the start of the last second

TimestampSeconds

An exact date and time, with a resolution of one second (no nanoseconds).

FieldTypeLabelDescription
seconds int64

Number of complete seconds since the start of the epoch

TokenAssociate.proto

Top

TokenAssociateTransactionBody

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.

FieldTypeLabelDescription
account AccountID

The account to be associated with the provided tokens

tokens TokenID repeated

The tokens to be associated with the provided account

TokenBurn.proto

Top

TokenBurnTransactionBody

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.

FieldTypeLabelDescription
token TokenID

The token for which to burn tokens. If token does not exist, transaction results in INVALID_TOKEN_ID

amount uint64

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.

TokenCreate.proto

Top

TokenCreateTransactionBody

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.

FieldTypeLabelDescription
name string

The publicly visible name of the token, limited to a UTF-8 encoding of length <tt>tokens.maxSymbolUtf8Bytes</tt>.

symbol string

The publicly visible token symbol, limited to a UTF-8 encoding of length <tt>tokens.maxTokenNameUtf8Bytes</tt>.

decimals uint32

The number of decimal places a token is divisible by. This field can never be changed!

initialSupply uint64

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.

treasury AccountID

The account which will act as a treasury for the token. This account will receive the specified initial supply

adminKey Key

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)

kycKey Key

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.

freezeKey Key

The key which can sign to freeze or unfreeze an account for token transactions. If empty, freezing is not possible

wipeKey Key

The key which can wipe the token balance of an account. If empty, wipe is not possible

supplyKey Key

The key which can change the supply of a token. The key is used to sign Token Mint/Burn operations

freezeDefault bool

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

expiry Timestamp

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

autoRenewAccount AccountID

An account which will be automatically charged to renew the token's expiration, at autoRenewPeriod interval

autoRenewPeriod Duration

The interval at which the auto-renew account will be charged to extend the token's expiry

memo string

The memo associated with the token (UTF-8 encoding max 100 bytes)

TokenDelete.proto

Top

TokenDeleteTransactionBody

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.

FieldTypeLabelDescription
token TokenID

The token to be deleted. If invalid token is specified, transaction will result in INVALID_TOKEN_ID

TokenDissociate.proto

Top

TokenDissociateTransactionBody

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 the provided account has a nonzero balance with any of the provided tokens, the transaction will resolve to TRANSACTION_REQUIRES_ZERO_TOKEN_BALANCES.

On success, associations between the provided account and tokens are removed.

FieldTypeLabelDescription
account AccountID

The account to be dissociated with the provided tokens

tokens TokenID repeated

The tokens to be dissociated with the provided account

TokenFreezeAccount.proto

Top

TokenFreezeAccountTransactionBody

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.

FieldTypeLabelDescription
token TokenID

The token for which this account will be frozen. If token does not exist, transaction results in INVALID_TOKEN_ID

account AccountID

The account to be frozen

TokenGetInfo.proto

Top

TokenGetInfoQuery

Gets information about Token instance

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither)

token TokenID

The token for which information is requested. If invalid token is provided, INVALID_TOKEN_ID response is returned.

TokenGetInfoResponse

Response when the client sends the node TokenGetInfoQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

tokenInfo TokenInfo

The information requested about this token instance

TokenInfo

The metadata about a Token instance

FieldTypeLabelDescription
tokenId TokenID

ID of the token instance

name string

The name of the token. It is a string of ASCII only characters

symbol string

The symbol of the token. It is a UTF-8 capitalized alphabetical string

decimals uint32

The number of decimal places a token is divisible by

totalSupply uint64

The total supply of tokens that are currently in circulation

treasury AccountID

The ID of the account which is set as Treasury

adminKey Key

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)

kycKey Key

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.

freezeKey Key

The key which can freeze or unfreeze an account for token transactions. If empty, freezing is not possible

wipeKey Key

The key which can wipe token balance of an account. If empty, wipe is not possible

supplyKey Key

The key which can change the supply of a token. The key is used to sign Token Mint/Burn operations

defaultFreezeStatus TokenFreezeStatus

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

defaultKycStatus TokenKycStatus

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

deleted bool

Specifies whether the token was deleted or not

autoRenewAccount AccountID

An account which will be automatically charged to renew the token's expiration, at autoRenewPeriod interval

autoRenewPeriod Duration

The interval at which the auto-renew account will be charged to extend the token's expiry

expiry Timestamp

The epoch second at which the token will expire

memo string

The memo associated with the token

TokenGrantKyc.proto

Top

TokenGrantKycTransactionBody

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.

FieldTypeLabelDescription
token TokenID

The token for which this account will be granted KYC. If token does not exist, transaction results in INVALID_TOKEN_ID

account AccountID

The account to be KYCed

TokenMint.proto

Top

TokenMintTransactionBody

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.

FieldTypeLabelDescription
token TokenID

The token for which to mint tokens. If token does not exist, transaction results in INVALID_TOKEN_ID

amount uint64

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.

TokenRevokeKyc.proto

Top

TokenRevokeKycTransactionBody

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

FieldTypeLabelDescription
token TokenID

The token for which this account will get his KYC revoked. If token does not exist, transaction results in INVALID_TOKEN_ID

account AccountID

The account to be KYC Revoked

TokenService.proto

Top

TokenService

Transactions and queries for the Token Service

Method NameRequest TypeResponse TypeDescription
createToken Transaction TransactionResponse

Creates a new Token by submitting the transaction

updateToken Transaction TransactionResponse

Updates the account by submitting the transaction

mintToken Transaction TransactionResponse

Mints an amount of the token to the defined treasury account

burnToken Transaction TransactionResponse

Burns an amount of the token from the defined treasury account

deleteToken Transaction TransactionResponse

Deletes a Token

wipeTokenAccount Transaction TransactionResponse

Wipes the provided amount of tokens from the specified Account ID

freezeTokenAccount Transaction TransactionResponse

Freezes the transfer of tokens to or from the specified Account ID

unfreezeTokenAccount Transaction TransactionResponse

Unfreezes the transfer of tokens to or from the specified Account ID

grantKycToTokenAccount Transaction TransactionResponse

Flags the provided Account ID as having gone through KYC

revokeKycFromTokenAccount Transaction TransactionResponse

Removes the KYC flag of the provided Account ID

associateTokens Transaction TransactionResponse

Associates tokens to an account

dissociateTokens Transaction TransactionResponse

Dissociates tokens from an account

getTokenInfo Query Response

Retrieves the metadata of a token

TokenUnfreezeAccount.proto

Top

TokenUnfreezeAccountTransactionBody

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.

FieldTypeLabelDescription
token TokenID

The token for which this account will be unfrozen. If token does not exist, transaction results in INVALID_TOKEN_ID

account AccountID

The account to be unfrozen

TokenUpdate.proto

Top

TokenUpdateTransactionBody

At consensus, updates an already created token to the given values.

If no value is given for a field, that field is left unchanged. For an immutable tokens (that is, a token without an admin key), only the expiry may be updated. Setting any other field in that case will cause the transaction status to resolve to TOKEN_IS_IMMUTABLE.

--- Signing Requirements ---

1. Whether or not a token has an admin key, its expiry can be extended with only the transaction payer's signature.

2. Updating any other field of a mutable token requires the admin key's signature.

3. If a new admin key is set, this new key must sign unless it is exactly an empty KeyList. This special sentinel key removes the existing admin key and causes the token to become immutable. (Other Key structures without a constituent Ed25519 key will be rejected with INVALID_ADMIN_KEY.)

4. If a new treasury is set, the new treasury account's key must sign the transaction.

FieldTypeLabelDescription
token TokenID

The Token to be updated

symbol string

The new publicly visible Token symbol, limited to a UTF-8 encoding of length <tt>tokens.maxTokenNameUtf8Bytes</tt>.

name string

The new publicly visible name of the Token, limited to a UTF-8 encoding of length <tt>tokens.maxSymbolUtf8Bytes</tt>.

treasury AccountID

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.

adminKey Key

The new admin key of the Token. If Token is immutable, transaction will resolve to TOKEN_IS_IMMUTABlE.

kycKey Key

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.

freezeKey Key

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.

wipeKey Key

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.

supplyKey Key

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.

autoRenewAccount AccountID

The new account which will be automatically charged to renew the token's expiration, at autoRenewPeriod interval.

autoRenewPeriod Duration

The new interval at which the auto-renew account will be charged to extend the token's expiry.

expiry Timestamp

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

memo google.protobuf.StringValue

If set, the new memo to be associated with the token (UTF-8 encoding max 100 bytes)

TokenWipeAccount.proto

Top

TokenWipeAccountTransactionBody

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.

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.

FieldTypeLabelDescription
token TokenID

The token for which the account will be wiped. If token does not exist, transaction results in INVALID_TOKEN_ID

account AccountID

The account to be wiped

amount uint64

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]

Transaction.proto

Top

Transaction

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.

FieldTypeLabelDescription
signedTransactionBytes bytes

SignedTransaction serialized into bytes

bodyBytes bytes

TransactionBody serialized into bytes, which needs to be signed

sigMap SignatureMap

The signatures on the body with the new format, to authorize the transaction

Fields with deprecated option

Name Option
bodyBytes

true

sigMap

true

TransactionBody.proto

Top

TransactionBody

A single transaction. All transaction types are possible here.

FieldTypeLabelDescription
transactionID TransactionID

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

nodeAccountID AccountID

The account of the node that submits the client's transaction to the network

transactionFee uint64

The maximum transaction fee the client is willing to pay

transactionValidDuration Duration

The transaction is invalid if consensusTimestamp > transactionID.transactionValidStart + transactionValidDuration

generateRecord bool

Should a record of this transaction be generated? (A receipt is always generated, but the record is optional)

memo string

Any notes or descriptions that should be put into the record (max length 100)

contractCall ContractCallTransactionBody

Calls a function of a contract instance

contractCreateInstance ContractCreateTransactionBody

Creates a contract instance

contractUpdateInstance ContractUpdateTransactionBody

Updates a contract

contractDeleteInstance ContractDeleteTransactionBody

Delete contract and transfer remaining balance into specified account

cryptoAddLiveHash CryptoAddLiveHashTransactionBody

Attach a new livehash to an account

cryptoCreateAccount CryptoCreateTransactionBody

Create a new cryptocurrency account

cryptoDelete CryptoDeleteTransactionBody

Delete a cryptocurrency account (mark as deleted, and transfer hbars out)

cryptoDeleteLiveHash CryptoDeleteLiveHashTransactionBody

Remove a livehash from an account

cryptoTransfer CryptoTransferTransactionBody

Transfer amount between accounts

cryptoUpdateAccount CryptoUpdateTransactionBody

Modify information such as the expiration date for an account

fileAppend FileAppendTransactionBody

Add bytes to the end of the contents of a file

fileCreate FileCreateTransactionBody

Create a new file

fileDelete FileDeleteTransactionBody

Delete a file (remove contents and mark as deleted until it expires)

fileUpdate FileUpdateTransactionBody

Modify information such as the expiration date for a file

systemDelete SystemDeleteTransactionBody

Hedera administrative deletion of a file or smart contract

systemUndelete SystemUndeleteTransactionBody

To undelete an entity deleted by SystemDelete

freeze FreezeTransactionBody

Freeze the nodes

consensusCreateTopic ConsensusCreateTopicTransactionBody

Creates a topic

consensusUpdateTopic ConsensusUpdateTopicTransactionBody

Updates a topic

consensusDeleteTopic ConsensusDeleteTopicTransactionBody

Deletes a topic

consensusSubmitMessage ConsensusSubmitMessageTransactionBody

Submits message to a topic

uncheckedSubmit UncheckedSubmitBody

tokenCreation TokenCreateTransactionBody

Creates a token instance

tokenFreeze TokenFreezeAccountTransactionBody

Freezes account not to be able to transact with a token

tokenUnfreeze TokenUnfreezeAccountTransactionBody

Unfreezes account for a token

tokenGrantKyc TokenGrantKycTransactionBody

Grants KYC to an account for a token

tokenRevokeKyc TokenRevokeKycTransactionBody

Revokes KYC of an account for a token

tokenDeletion TokenDeleteTransactionBody

Deletes a token instance

tokenUpdate TokenUpdateTransactionBody

Updates a token instance

tokenMint TokenMintTransactionBody

Mints new tokens to a token's treasury account

tokenBurn TokenBurnTransactionBody

Burns tokens from a token's treasury account

tokenWipe TokenWipeAccountTransactionBody

Wipes amount of tokens from an account

tokenAssociate TokenAssociateTransactionBody

Associate tokens to an account

tokenDissociate TokenDissociateTransactionBody

Dissociate tokens from an account

scheduleCreate ScheduleCreateTransactionBody

Creates a scheduled transaction instance

scheduleDelete ScheduleDeleteTransactionBody

Deletes a scheduled transaction instance

scheduleSign ScheduleSignTransactionBody

Signs a scheduled transaction instance

Fields with deprecated option

Name Option
generateRecord

true

TransactionContents.proto

Top

SignedTransaction

FieldTypeLabelDescription
bodyBytes bytes

TransactionBody serialized into bytes, which needs to be signed

sigMap SignatureMap

The signatures on the body with the new format, to authorize the transaction

TransactionGetFastRecord.proto

Top

TransactionGetFastRecordQuery

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).

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

transactionID TransactionID

The ID of the transaction for which the record is requested.

TransactionGetFastRecordResponse

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.

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

transactionRecord TransactionRecord

The requested transaction records

TransactionGetReceipt.proto

Top

TransactionGetReceiptQuery

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

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

transactionID TransactionID

The ID of the transaction for which the receipt is requested.

includeDuplicates bool

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 <tt>INVALID_NODE_ACCOUNT</tt> nor <tt>INVALID_PAYER_SIGNATURE</tt>; <b>or</b>, if no such receipt exists, the receipt of processing the first transaction to reach consensus with the given transaction id..

TransactionGetReceiptResponse

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

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither

receipt TransactionReceipt

Either the receipt of processing the first consensus transaction with the given id whose status was neither <tt>INVALID_NODE_ACCOUNT</tt> nor <tt>INVALID_PAYER_SIGNATURE</tt>; <b>or</b>, if no such receipt exists, the receipt of processing the first transaction to reach consensus with the given transaction id.

duplicateTransactionReceipts TransactionReceipt repeated

The receipts of processing all consensus transaction with the same id as the distinguished receipt above, in chronological order.

TransactionGetRecord.proto

Top

TransactionGetRecordQuery

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.

FieldTypeLabelDescription
header QueryHeader

Standard info sent from client to node, including the signed payment, and what kind of response is requested (cost, state proof, both, or neither).

transactionID TransactionID

The ID of the transaction for which the record is requested.

includeDuplicates bool

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 <tt>INVALID_NODE_ACCOUNT</tt> nor <tt>INVALID_PAYER_SIGNATURE</tt>; <b>or</b>, if no such record exists, the record of processing the first transaction to reach consensus with the given transaction id..

TransactionGetRecordResponse

Response when the client sends the node TransactionGetRecordQuery

FieldTypeLabelDescription
header ResponseHeader

Standard response from node to client, including the requested fields: cost, or state proof, or both, or neither.

transactionRecord TransactionRecord

Either the record of processing the first consensus transaction with the given id whose status was neither <tt>INVALID_NODE_ACCOUNT</tt> nor <tt>INVALID_PAYER_SIGNATURE</tt>; <b>or</b>, if no such record exists, the record of processing the first transaction to reach consensus with the given transaction id.

duplicateTransactionRecords TransactionRecord repeated

The records of processing all consensus transaction with the same id as the distinguished record above, in chronological order.

TransactionReceipt.proto

Top

TransactionReceipt

The summary of a transaction's result so far. If the transaction has not reached consensus, this result will be necessarily incomplete.

FieldTypeLabelDescription
status ResponseCodeEnum

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

accountID AccountID

In the receipt of a CryptoCreate, the id of the newly created account

fileID FileID

In the receipt of a FileCreate, the id of the newly created file

contractID ContractID

In the receipt of a ContractCreate, the id of the newly created contract

exchangeRate ExchangeRateSet

The exchange rates in effect when the transaction reached consensus

topicID TopicID

In the receipt of a ConsensusCreateTopic, the id of the newly created topic.

topicSequenceNumber uint64

In the receipt of a ConsensusSubmitMessage, the new sequence number of the topic that received the message

topicRunningHash bytes

In the receipt of a ConsensusSubmitMessage, the new running hash of the topic that received the message. This 48-byte field is the output of a particular SHA-384 digest whose input data are determined by the value of the topicRunningHashVersion below. The bytes of each uint64 or uint32 are to be in Big-Endian format. IF the topicRunningHashVersion is '0' or '1', then the input data to the SHA-384 digest are, in order: --- 1. The previous running hash of the topic (48 bytes) 2. The topic's shard (8 bytes) 3. The topic's realm (8 bytes) 4. The topic's number (8 bytes) 5. The number of seconds since the epoch before the ConsensusSubmitMessage reached consensus (8 bytes) 6. The number of nanoseconds since 5. before the ConsensusSubmitMessage reached consensus (4 bytes) 7. The topicSequenceNumber from above (8 bytes) 8. The message bytes from the ConsensusSubmitMessage (variable). IF the topicRunningHashVersion is '2', then the input data to the SHA-384 digest are, in order: --- 1. The previous running hash of the topic (48 bytes) 2. The topicRunningHashVersion below (8 bytes) 3. The topic's shard (8 bytes) 4. The topic's realm (8 bytes) 5. The topic's number (8 bytes) 6. The number of seconds since the epoch before the ConsensusSubmitMessage reached consensus (8 bytes) 7. The number of nanoseconds since 6. before the ConsensusSubmitMessage reached consensus (4 bytes) 8. The topicSequenceNumber from above (8 bytes) 9. The output of the SHA-384 digest of the message bytes from the consensusSubmitMessage (48 bytes) Otherwise, IF the topicRunningHashVersion is '3', then the input data to the SHA-384 digest are, in order: --- 1. The previous running hash of the topic (48 bytes) 2. The topicRunningHashVersion below (8 bytes) 3. The payer account's shard (8 bytes) 4. The payer account's realm (8 bytes) 5. The payer account's number (8 bytes) 6. The topic's shard (8 bytes) 7. The topic's realm (8 bytes) 8. The topic's number (8 bytes) 9. The number of seconds since the epoch before the ConsensusSubmitMessage reached consensus (8 bytes) 10. The number of nanoseconds since 9. before the ConsensusSubmitMessage reached consensus (4 bytes) 11. The topicSequenceNumber from above (8 bytes) 12. The output of the SHA-384 digest of the message bytes from the consensusSubmitMessage (48 bytes)

topicRunningHashVersion uint64

In the receipt of a ConsensusSubmitMessage, the version of the SHA-384 digest used to update the running hash.

tokenID TokenID

In the receipt of a CreateToken, the id of the newly created token

newTotalSupply uint64

In the receipt of TokenMint, TokenWipe, TokenBurn, the current total supply of this token

scheduleID ScheduleID

In the receipt of a CreateSchedule, the id of the newly created Scheduled Entity

TransactionRecord.proto

Top

TransactionRecord

Response when the client sends the node TransactionGetRecordResponse

FieldTypeLabelDescription
receipt TransactionReceipt

The status (reach consensus, or failed, or is unknown) and the ID of any new account/file/instance created.

transactionHash bytes

The hash of the Transaction that executed (not the hash of any Transaction that failed for having a duplicate TransactionID)

consensusTimestamp Timestamp

The consensus timestamp (or null if didn't reach consensus yet)

transactionID TransactionID

The ID of the transaction this record represents

memo string

The memo that was submitted as part of the transaction (max 100 bytes)

transactionFee uint64

The actual transaction fee charged, not the original transactionFee value from TransactionBody

contractCallResult ContractFunctionResult

Record of the value returned by the smart contract function (if it completed and didn't fail) from ContractCallTransaction

contractCreateResult ContractFunctionResult

Record of the value returned by the smart contract constructor (if it completed and didn't fail) from ContractCreateTransaction

transferList TransferList

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.

tokenTransferLists TokenTransferList repeated

All Token transfers as a result of this transaction

scheduleRef ScheduleID

Reference to the scheduled transaction ID that this transaction record represent

TransactionResponse.proto

Top

TransactionResponse

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).

FieldTypeLabelDescription
nodeTransactionPrecheckCode ResponseCodeEnum

The response code that indicates the current status of the transaction.

cost uint64

If the response code was INSUFFICIENT_TX_FEE, the actual transaction fee that would be required to execute the transaction.

UncheckedSubmit.proto

Top

UncheckedSubmitBody

Submit an arbitrary (serialized) Transaction to the network without prechecks. Requires superuser privileges.

FieldTypeLabelDescription
transactionBytes bytes

The serialized bytes of the Transaction to be submitted without prechecks

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)