syntax = "proto3";
package proto;
import "Timestamp.proto";
import "Duration.proto";
option java_package = "com.hederahashgraph.api.proto.java";
option java_multiple_files = true;
/* Each shard has a nonnegative shard number. Each realm within a given shard has a nonnegative realm number (that number might be reused in other shards). And each account, file, and smart contract instance within a given realm has a nonnegative number (which might be reused in other realms). Every account, file, and smart contract instance is within exactly one realm. So a FileID is a triplet of numbers, like 0.1.2 for entity number 2 within realm 1 within shard 0. Each realm maintains a single counter for assigning numbers, so if there is a file with ID 0.1.2, then there won't be an account or smart contract instance with ID 0.1.2.
Everything is partitioned into realms so that each Solidity smart contract can access everything in just a single realm, locking all those entities while it's running, but other smart contracts could potentially run in other realms in parallel. So realms allow Solidity to be parallelized somewhat, even though the language itself assumes everything is serial. */
message ShardID {
int64 shardNum = 1; //the shard number (nonnegative)
}
/* The ID for a realm. Within a given shard, every realm has a unique ID. Each account, file, and contract instance belongs to exactly one realm. */
message RealmID {
int64 shardNum = 1; //the shard number (nonnegative)
int64 realmNum = 2; //the realm number (nonnegative)
}
/* The ID for an a cryptocurrency account */
message AccountID {
int64 shardNum = 1; //the shard number (nonnegative)
int64 realmNum = 2; //the realm number (nonnegative)
int64 accountNum = 3; //a nonnegative number unique within its realm
}
/* The ID for a file */
message FileID {
int64 shardNum = 1; //the shard number (nonnegative)
int64 realmNum = 2; //the realm number (nonnegative)
int64 fileNum = 3; //a nonnegative number unique within its realm
}
/* The ID for a smart contract instance */
message ContractID {
int64 shardNum = 1; //the shard number (nonnegative)
int64 realmNum = 2; //the realm number (nonnegative)
int64 contractNum = 3; //a nonnegative number unique within its realm
}
/* The ID for a transaction. This is used for retrieving receipts and records for a transaction, for appending to a file right after creating it, for instantiating a smart contract with bytecode in a file just created, and internally by the network for detecting when duplicate transactions are submitted. A user might get a transaction processed faster by submitting it to N nodes, each with a different node account, but all with the same TransactionID. Then, the transaction will take effect when the first of all those nodes submits the transaction and it reaches consensus. The other transactions will not take effect. So this could make the transaction take effect faster, if any given node might be slow. However, the full transaction fee is charged for each transaction, so the total fee is N times as much if the transaction is sent to N nodes. */
message TransactionID {
Timestamp transactionValidStart = 1; // the transaction is invalid if consensusTimestamp < transactionID.transactionStartValid
AccountID accountID = 2; //the account that paid for this transaction
}
/* 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. The current API only allows the nesting to a depth of 3 levels, such as the key being a list of threshold keys, each of which contains a list of primitive keys (e.g., ed25519). In the future, this requirement may be relaxed, to allow deeper nesting.
*/
message Key {
oneof key {
ContractID contractID = 1; // smart contract instance that is authorized as if it had signed with a key
bytes ed25519 = 2; // ed25519 public key
bytes RSA_3072 = 3; //RSA-3072 public key
bytes ECDSA_384 = 4; //ECDSA with the p-384 curve public key
ThresholdKey thresholdKey = 5; // a threshold N followed by a list of M keys, any N of which are required to form a valid signature
KeyList keyList = 6; // a list of Keys.
}
}
/* A set of public keys that are used together to form a threshold signature. If the threshold is N and there are M keys, then this is an N of M threshold signature. If an account is associated with ThresholdKeys, then a transaction to move cryptocurrency out of it must be signed by a list of M signatures, where at most M-N of them are blank, and the other at least N of them are valid signatures corresponding to at least N of the public keys listed here. */
message ThresholdKey {
uint32 threshold = 1; // a valid signature set must have at least this many signatures
KeyList keys = 2; // list of all the keys that can sign
}
/* A list of keys */
message KeyList {
repeated Key keys = 1; // list of keys
}
/* 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.
*/
message Signature {
oneof signature {
bytes contract = 1; // smart contract virtual signature (always length zero)
bytes ed25519 = 2; // ed25519 signature
bytes RSA_3072 = 3; //RSA-3072 signature
bytes ECDSA_384 = 4; //ECDSA p-384 signature
ThresholdSignature thresholdSignature = 5; // a list of signatures for a single N-of-M threshold Key. This must be a list of exactly M signatures, at least N of which are non-null.
SignatureList signatureList = 6; // a list of M signatures, each corresponding to a Key in a KeyList of the same length.
}
}
/* 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. */
message ThresholdSignature {
SignatureList sigs = 2; // for an N-of-M threshold key, this is a list of M signatures, at least N of which must be non-null
}
/* The signatures corresponding to a KeyList of the same length */
message SignatureList {
repeated Signature sigs = 2; // each signature corresponds to a Key in the KeyList
}
/* The functionality provided by hedera hashgraph */
enum HederaFunctionality {
CryptoCreate = 0; // crypto create account
CryptoTransfer = 1; // crypto transfer
CryptoUpdate = 2; // crypto update account
CryptoDelete = 3; // crypto delete account
CryptoAddClaim = 4; // crypto add claim to the account
CryptoDeleteClaim = 5; // crypto delete claim to the 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
CryptoGetClaim = 21; // Crypto get the claim
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
}
/* The different components used for fee calculation */
message FeeComponents {
int64 min = 1; // the minimum fees that needs to be paid
int64 max = 2; // the maximum fees that can be submitted
int64 constant = 3; // a constant determined by the business to calculate the fees
int64 bpt = 4; // bytes per transaction
int64 vpt = 5; // verifications per transaction
int64 rbs = 6; // ram byte seconds
int64 sbs = 7; // storage byte seconds
int64 gas = 8; // ethereum gas
int64 tv = 9; // transaction value (crypto transfers amount, tv is in tiny bars divided by 1000, rounded down)
int64 bpr = 10; // bytes per response
int64 sbpr = 11; // storage bytes per response
}
/* The fees for a specific transaction or query based on the fee data. */
message TransactionFeeSchedule {
HederaFunctionality hederaFunctionality = 1; // Specific Transaction or Query
FeeData feeData = 2; // the fee information about the query/data
}
/* The total fees charged for a transaction. It contains three parts namely node data, network data and service data */
message FeeData {
FeeComponents nodedata = 1; // Fee charged by Node for this functionality
FeeComponents networkdata = 2; // Fee charged for network operations by Hedera
FeeComponents servicedata = 3; // Fee charged for providing service by Hedera
}
/* The fee schedule for a specific hedera functionality and the time period this fee will be valid for the transaction */
message FeeSchedule {
repeated TransactionFeeSchedule transactionFeeSchedule = 1;
Duration feeScheduleValidityDuration = 2; // the valid duration for the fee schedule
}
/* The information about a node */
message NodeAddress {
bytes ipAddress = 1; // the ip address of the Node
int32 portno = 2; // the port number of the grpc server for the node
bytes memo = 3; // the memo field of the node
}
/* Gives the node addresses in the address book */
message NodeAddressBook {
repeated NodeAddress nodeAddress = 1;
}