@hashgraph/proto

Hedera protobufs

The authoritative repository of protocol buffers used by the Hedera Hashgraph public network, especially to define its gRPC API. Other repositories are used to deploy language-specific libraries generated from the *.proto files in the following repositories:

• Java
• Go
• JS & Typescript
• C++
• Swift

Overview of services

There are five primary service families, which inter-operate on entities controlled by one (or more) Ed25519 keypairs:

1. The cryptocurrency service, for cryptocurrency accounts with transfers denominated in hBar (ℏ).
2. The consensus service, for fast and unbiased ordering of opaque binary messages exchanged on arbitrary topics.
3. The smart contract service, for execution of Solidity contract creations and calls; contract may both possess ℏ themselves and exchange it with non-contract accounts.
4. The file service, for storage and retrieval of opaque binary data.
5. The token service, for token related operations such as create, update, mint, burn, transfer etc.

There are also four secondary service families:

1. The network service, for operations scoped to the network or its constituent nodes rather user-controlled entities as above.
2. The scheduling service, for scheduling a transaction to be executed when the ledger has received enough prequisite signatures.
3. The freeze service, for use by privileged accounts to suspend network operations during a maintenance window.
4. The util service, for utility operations on the network.

It is important to note that most network services are gated by fees which must be paid in ℏ from a cryptocurrency account. The payer authorizes a fee by signing an appropriate transaction with a sufficient subset of the Ed25519 key(s) associated to their account.

Overview of state

State directory and its subdirectories contain the protobuf files that define the state of the network. The state is divided into the following subdirectories, based on the service modules:

1. Token - The state of the Token service.
2. Consensus - The state of the Consensus service.

The state directory and its subdirectories are in preview and are subject to change.

For Developers

Branching

This repository uses a simple branching model with only two distinguished branches:

1. The head of main points to the latest protobufs blessed for deployment to mainnet. Tags such as v0.12.0 mark commits used for testnet and mainnet deploys.
2. The head of develop points to the latest candidate for the next tag in main. Tags suffixed with -alpha.x mark commits used for previewnet deploys.

PBJ Package Support

Proto files in this repo are generated into two kinds of Java files, one using protoc and other using PBJ a custom java code generation library for Hedera. To support PBJ all proto files need to have an option of the form:

// <<<pbj.java_package = "com.hedera.hapi.node.token">>> This comment is special code for setting PBJ Compiler java package

To specify the Java package for PBJ generated model objects. This option is ignored by protoc. PBJ ignores the default option option java_package = "com.hederahashgraph.api.proto.java"; which is used by protoc to generate Java files.