hashgraph / hedera-protobufs-java

The protobuf message files defining the Hedera Hashgraph API

Hedera Hashgraph Protocol Buffer API Message Definitions

The Hedera Hashgraph API is implemented with protocol buffers, Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data. This repository contains the current version of the files used to define the API.

Documentation

The protobuf files themselves contain detailed comments which help understand not only the message itself but also some of the features and capabilities of the Hedera Hashgraph network.

The /docs folder of this project contains automatically generated documents in html and markdown format to help navigate through the message definitions.

NestedDoc.html - nested HTML document to help navigate messages that contain other message definitions (large document that takes a while to open) NotNestedDoc.html - flat HTML document NotNestedDoc.md - flat markdown document

Note: the HAPI.html document is a large document and may take a few seconds to load in a browser.

Additional resources

If you are unfamiliar with protocol buffers (or need a refresher), you may consult the following web resources:

• Protocol Buffers : https://developers.google.com/protocol-buffers/
• gRPC : https://grpc.io

Deploy to Maven

You will need the appropriate credentials to do so

• Update the version number in the pom.xml (ensure pom.xml has x.x.x-SNAPSHOT for version)
• Build the project with mvn clean install
• Re-generate the documentation

cd docgenerator
java -jar proto2html.jar "HAPI Documentation" ../src/main/proto/ ../docs

cd ..

Commit all changes to github

mvn release:clean release:prepare (you will be prompted to confirm version numbers, etc...)

mvn release:perform

navigate to Nexus Repository Manager https://oss.sonatype.org/index.html#stagingRepositories and release the newly created repository.

hedera-protobufs-java's Issues

HIP-24

Problem

Make appropriate changes to supper HIP-24

Solution

Follow hashgraph/hedera-protobufs#96

Alternatives

No response

Add missing Response codes for HIP-18

When the fractional custom fee maximum_amount is less than minimum_amount, add a new response code FRACTIONAL_FEE_MAX_AMOUNT_LESS_THAN_MIN_AMOUNT

Deploy separate build artifact for Android with protobuf-lite

This package as-is when imported in the Java SDK cannot be used subsequently in an Android project without increasing the minApiVersion to 26 which cuts off about 63% of the market according to https://developer.android.com/about/dashboards

This is because the regular protobuf-java package is not built for Android and uses intrinsics that are too new:

> Transform artifact protobuf-java.jar (com.google.protobuf:protobuf-java:3.10.0) with DexingNoClasspathTransform
AGPBI: {"kind":"error","text":"MethodHandle.invoke and MethodHandle.invokeExact are only supported starting with Android O (--min-api 26)","sources":[{}],"tool":"D8"}

The official recommendation is to use protobuf-lite which is a separate package with differently named classes and a different protoc invocation: https://github.com/protocolbuffers/protobuf/blob/master/java/lite.md

We can switch this out with profiles and tag the Android configuration with a android classifier, then build and deploy both the full Java version with no classifier and a lightweight Android version with the android classifier:

• https://maven.apache.org/guides/introduction/introduction-to-profiles.html
• https://stackoverflow.com/a/3094466
• https://maven.apache.org/plugins/maven-deploy-plugin/examples/deploying-with-classifiers.html

(We can then use the same approach to switch which version of the hedera-protobuf package we use in the Java SDK.)

Update messages to support auto account creation

Problem

Hedera Services would like to support new way to create accounts using an alias (public key)

Solution

Make the following changes in our protobufs:

1. Add an alias public key to the existing AccountID. Any account should have unique alias or accountNum set.

message AccountID {
    int64 shardNum = 1;
    int64 realmNum = 2;
 oneof account {
    int64 accountNum = 3;
    Key alias = 4;
    }
}

2. The account info should have information about alias

bytes alias;

Alternatives

No response

Upgrade io.grpc dependencies

The io.grpc group dependencies this package links are quite old at 1.13.1; the latest version is 1.23.0 and we were previously linking 1.20 in hedera-sdk-java but going to have to downgrade due to switching.

Update Freeze transaction to use instant in time

Please reference to hedera services issue hashgraph/hedera-services#1192 for details.

Update messages to support ECDSA secp256k1 keys

Problem

Hedera Services currently uses Ed25519 exclusively, but some users would like to use ECDSA (with the secp256k1 curve as on the Bitcoin network).

Solution

Make two changes in our protobufs to enable support for secp256k1:

1. Extend the SignaturePair oneof with a bytes ecdsa_secp256k1 choice.
2. Extend the Key oneof with a bytes ecdsa_secp256k1 choice whose value must be the 33-byte compressed form that begins with 0x02 for a curve point with even y coordinate, and 0x03 for a curve point with odd y coordinate.

(NOTE: the Signature message type is deprecated and will not be extended in this case---or ever.)

Missing MAX_GAS_LIMIT_EXCEEDED & MAX_FILE_SIZE_EXCEEDED response codes

The following response codes are in the services protobuf but missing from the public protobuf and need to be added:

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

Update HCS protobuf for final 0.4 release

• Remove TopicID from SystemDelete/SystemUndelete. This functionality will be added in services release 0.5, not 0.4.
• Deprecate new response code AUTORENEW_ACCOUNT_SIGNATURE_MISSING. This will be removed when 0.4 is release to testnet. INVALID_SIGNATURE will be used consistently for cases of missing required signatures on an entity (distinct from the transaction payer's signature).
• Update a few response codes on the HCS branch unrelated to HCS that are still being added in 0.4 (MAX_GAS_LIMIT_EXCEEDED, MAX_FILE_SIZE_EXCEEDED, TRANSFER_ACCOUNT_SAME_AS_DELETE_ACCOUNT spelling fixed)

Add new response code for HCS message size limit

Please check the details in hedera services issue hashgraph/hedera-services#1145

transaction query examples.md has typo

Contact should read contract in the header of one of the examples

Allow fractional fees to be charged to _either_ sender or receiver

Problem

Please refer to the description in services issue #1926: hashgraph/hedera-services#1926

Solution

message FractionalFee {
  Fraction fractional_amount = 1; // The fraction of the transferred units to assess as a fee
  int64 minimum_amount = 2; // The minimum amount to assess
  int64 maximum_amount = 3; // The maximum amount to assess (zero implies no maximum)
  bool netOfTransfers = 4; // If true, assesses the fee to the sender, so the receiver gets the full amount from the token transfer list, and the sender is charged an additional fee; if false, the receiver does NOT get the full amount, but only what is left over after paying the fractional fee
}

Alternatives

No response

Add new response code RECEIVER_SIG_REQUIRED

Add new response code RECEIVER_SIG_REQUIRED to refine the INVALID_SIGNATURE response code.

Resolves issue : hashgraph/hedera-services#1556

Update Freeze transaction to use instant in time

Problem

Currently, the freeze transaction is sending startHour, startMin, endHour, endMin to specify that the services should be frozen at startHour and startMin from now, and should wake up at endHour and endMin from now.

Need to change this to use startTime and endTime of Instant to.

Solution

Need to make the following change of the FreezeTransactionBody:

message FreezeTransactionBody {
    int32 startHour = 1 [deprecated = true]; // The start hour (in UTC time), a value between 0 and 23
    int32 startMin = 2 [deprecated = true]; // The start minute (in UTC time), a value between 0 and 59
    int32 endHour = 3 [deprecated = true]; // The end hour (in UTC time), a value between 0 and 23
    int32 endMin = 4 [deprecated = true]; // The end minute (in UTC time), a value between 0 and 59
    FileID updateFile = 5; // The ID of the file needs to be updated during a freeze transaction
    bytes fileHash = 6; // The hash value of the file, used to verify file content before performing freeze and update
    Timestamp startTime = 7; // the freeze start Timestamp
}

Alternatives

No response

transaction and query examples.md is not up to date

Doc needs updating with messages/responses for version 0.2.0. It's currently showing 0.1.0 messages.

Add new `ReturnToken` transaction

Problem

follow : hashgraph/hedera-services#2331

Solution

Follow : hashgraph/hedera-protobufs#103

Alternatives

No response

Enhance Schedule Creation to allow creators of a Scheduled Transaction to automatically sign a created schedule.

Problem

Duplicate of hashgraph/hedera-services#2269

Solution

Follow hashgraph/hedera-protobufs#97

Alternatives

No response

Add Appropriate RepsonseCodes for CustomFee involving NFTs

Problem

1. If a fee schedule denomination is a token, it must be a Fungible Token
2. A Non Fungible Token cannot have a fraction fee in its FeeSchedule

Solution

CUSTOM_FEE_DENOMINATION_MUST_BE_FUNGIBLE_COMMON = 245; // If a fee schedule denomination is a token, it must be a Fungible Token
CUSTOM_FRACTIONAL_FEE_ONLY_ALLOWED_FOR_FUNGIBLE_COMMON = 246; // A Non Fungible Token cannot have a fraction fee in its FeeSchedule

Add new token associations to transaction record

Problem

Issue for hashgraph/hedera-protobufs#79

Enable GPG signing on commits

Each commit is signed by the developers GPG key.

Reject invalid number of automatic association slots

Problem

During a CryptoCreate or CryptoUpdate, if the proposed automatic association slots is more than the allowed tokenAssociations on the network, we should fail with REQUESTED_NUM_AUTOMATIC_ASSOCIATIONS_EXCEEDS_ASSOCIATION_LIMIT

Solution

Add a new response code REQUESTED_NUM_AUTOMATIC_ASSOCIATIONS_EXCEEDS_ASSOCIATION_LIMIT

Original issue : hashgraph/hedera-protobufs#85

Alternatives

No response

Rename master branch to main

0.0.101 NodeAddressBook contains duplicate entries for each distinct IP

Summary
As a Hedera Services client, I need the address book to contain one entry per node so it's easier to consume and doesn't duplicate information. Currently, for the 0.0.101 address book that contains IP address information it duplicates each NodeAddress for each distinct IP that that node has. This is confusing since the node count shows as 39 in mainnet (via NodeAddressBook.getNodeAddressCount()) despite there only being 13ish nodes. It's also wasteful to duplicate information as every client who wants to communicate with the network will be pulling this file to get up to date IP information.

The proto currently looks like this:

message NodeAddress {
    bytes ipAddress = 1; // The ip address of the Node with separator & octets
    int32 portno = 2; // The port number of the grpc server for the node
    bytes memo = 3; // The memo field of the node (usage to store account ID is deprecated)
    string RSA_PubKey = 4; // The RSA public key of the node
    int64 nodeId = 5; // A non-sequential identifier for the node
    AccountID nodeAccountId = 6; // The account to be paid for queries and transactions sent to this node
    bytes nodeCertHash = 7; // A hash of the X509 cert used for gRPC traffic to this node
}

message NodeAddressBook {
    repeated NodeAddress nodeAddress = 1; // Contains multiple Node Address for the network
}

Possible resolution
File 0.0.101 will be NodeAddressBookAbbreviated
File 0.0.102 will be NodeAddressBook

message NodeEndpoint {
    string ipAddress = 1; // The IP address of the node
    string port = 2; // The port of the node
}

message NodeAddressAbbreviated {
    bytes ipAddress = 1 [deprecated=true]; // The IP address of the Node with separator & octets
    int32 portno = 2 [deprecated=true];// The port number of the grpc server for the node
    bytes memo = 3; [deprecated=true]; // The memo field of the node (usage to store account ID is deprecated)
    string RSA_PubKey = 4 [deprecated=true]; // The RSA public key of the node
    int64 nodeId = 5; // A non-sequential identifier for the node. This value is the key between the full and abbreviated address books 
    AccountID nodeAccountId = 6; // The account to be paid for queries and transactions sent to this node
    bytes nodeCertHash = 7 [deprecated=true]; // A hash of the X509 cert used for gRPC traffic to this node
    repeated NodeEndpoint = 8; // A node's IP address and port
}

message NodeAddressBookAbbreviated {
    repeated NodeAddressAbbreviated nodeAddressAbbreviated = 1; // Contains minimal node details for the network
}

message NodeAddress {
    bytes ipAddress = 1 [deprecated=true]; // The IP address of the Node with separator & octets
    int32 portno = 2 [deprecated=true]; // The port number of the grpc server for the node
    bytes memo = 3 [deprecated=true]; // The memo field of the node (usage to store account ID is deprecated)
    string RSA_PubKey = 4; // The RSA public key of the node
    int64 nodeId = 5; // A non-sequential identifier for the node. This value is the key between the full and abbreviated address books 
    AccountID nodeAccountId = 6; // The account to be paid for queries and transactions sent to this node
    bytes nodeCertHash = 7; // A hash of the X509 cert used for gRPC traffic to this node
    repeated NodeEndpoint = 8; // A node's IP address and port
    string description = 9; // A description of the node. Max 100 bytes.
    int64 stake = 10; // The amount of tinybars staked to this node 
}

message NodeAddressBook {
    repeated NodeAddress nodeAddress = 1; // Contains all details of the nodes for the network
}

Wrong documentation for DeleteContract

https://github.com/hashgraph/hedera-protobuf/blob/696830b8e75b68849c6b68eec1e841ef55b5ba1c/src/main/proto/ContractDelete.proto#L10

The documentation for ContractDelete is using the same documentation from ContractUpdate. However, it should reflect the actual behavior of ContractDelete

https://github.com/hashgraph/hedera-protobuf/blob/696830b8e75b68849c6b68eec1e841ef55b5ba1c/src/main/proto/ContractUpdate.proto#L12

HIP 18 : Add Messages required for customFees in HBAR and TokenUnits

Resolves issue : hashgraph/hedera-services#1586

Add Messages:

• CustomTransferFeeInTokens To specify custom Fee to pay in Token Units of a TokenId to a receiver receiverAccountID
• CustomTokenUnitFees To specify the tansferList generated because of the associated CustomTransferFeeInTokens
• CustomTransferFeeInHbar To specify custom Fee to pay in HBAR to a receiver receiverAccountID
• CustomHbarFees to Specify the tansferList generated because of the associated CustomTransferFeeInHbar
• Add CustomTransferFeeInTokens and CustomTransferFeeInHbar to TokenCreate, TokenUpdate transaction bodies and to TokenInfo
• Add CustomTokenUnitFees and CustomHbarFees to TransactionRecord

Unused Protobuf imports produce compile warnings.

The following compiler warnings are produced when compiling the protobuf files:

• BasicTypes.proto(6,1): warning : warning: Import Duration.proto but not used.
• Freeze.proto(9,1): warning : warning: Import Timestamp.proto but not used.
• Freeze.proto(8,1): warning : warning: Import Duration.proto but not used.
• ResponseHeader.proto(8,1): warning : warning: Import TransactionResponse.proto but not used.
• Transaction.proto(9,1): warning : warning: Import Duration.proto but not used.