Skip to content

Commit 7d62853

Browse files
Ndacyayisenga-droidNdacyayisenga-droid
committed
Initialise hiero-enterprise-java docs
Signed-off-by: Ndacyayisenga-droid <[email protected]>
1 parent 9f631a1 commit 7d62853

File tree

1 file changed

+181
-0
lines changed

1 file changed

+181
-0
lines changed

‎docs/DEVELOPER.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Hiero Enterprise Java - Developer Documentation
2+
3+
## Table of Contents
4+
1. [Introduction](#introduction)
5+
2. [Project Overview](#project-overview)
6+
3. [Architecture Overview](#architecture-overview)
7+
4. [Module Structure](#module-structure)
8+
5. [Core Concepts](#core-concepts)
9+
6. [How Everything Works Together](#how-everything-works-together)
10+
11+
12+
## Introduction
13+
14+
Welcome to the **Hiero Enterprise Java** codebase! This is a Java library that provides enterprise-grade integration with the Hiero blockchain network. If you're new to Java and blockchain development, don't worry - this documentation will guide you through everything step by step.
15+
16+
### What is Hiero?
17+
Hiero is a blockchain network (currently based on Hedera Hashgraph) that allows you to:
18+
- Create and manage accounts
19+
- Store files on the blockchain
20+
- Create and transfer tokens (fungible and NFTs)
21+
- Deploy and interact with smart contracts
22+
- Create topics for messaging
23+
- Query network information
24+
25+
### What does this library do?
26+
This library provides a **high-level, easy-to-use interface** for Java applications to interact with the Hiero blockchain. It handles all the complex blockchain communication details so you can focus on your business logic.
27+
28+
## Project Overview
29+
30+
### Project Structure
31+
```
32+
hiero-enterprise/
33+
├── hiero-enterprise-base/ # Core functionality
34+
├── hiero-enterprise-spring/ # Spring Boot integration
35+
├── hiero-enterprise-microprofile/ # MicroProfile integration
36+
├── hiero-enterprise-test/ # Testing utilities
37+
├── hiero-enterprise-spring-sample/ # Spring Boot example
38+
├── hiero-enterprise-microprofile-sample/ # MicroProfile example
39+
└── pom.xml # Main Maven configuration
40+
```
41+
42+
### Key Technologies Used
43+
- **Java 17** - Modern Java features
44+
- **Maven** - Build and dependency management
45+
- **Spring Boot** - Enterprise Java framework
46+
- **Hedera SDK** - Blockchain communication
47+
- **MicroProfile** - Enterprise Java standards
48+
- **JUnit 5** - Testing framework
49+
50+
## Architecture Overview
51+
52+
### High-Level Architecture
53+
```
54+
┌─────────────────────────────────────────────────────────────┐
55+
│ Your Application │
56+
├─────────────────────────────────────────────────────────────┤
57+
│ Spring Boot / MicroProfile │
58+
├─────────────────────────────────────────────────────────────┤
59+
│ Hiero Enterprise Library │
60+
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
61+
│ │ Client Layer │ │ Protocol Layer │ │ Mirror Node │ │
62+
│ │ │ │ │ │ Layer │ │
63+
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
64+
├─────────────────────────────────────────────────────────────┤
65+
│ Hedera SDK │
66+
├─────────────────────────────────────────────────────────────┤
67+
│ Hiero Network │
68+
└─────────────────────────────────────────────────────────────┘
69+
```
70+
71+
### Three-Layer Architecture
72+
73+
1. **Client Layer** - High-level, business-focused APIs
74+
2. **Protocol Layer** - Low-level blockchain communication
75+
3. **Mirror Node Layer** - Query historical data
76+
77+
## Module Structure
78+
79+
### 1. hiero-enterprise-base
80+
**Purpose**: Core functionality that works with any Java framework
81+
82+
**Key Components**:
83+
- `AccountClient` - Create and manage accounts
84+
- `FileClient` - Store and retrieve files
85+
- `TokenClient` - Handle fungible tokens
86+
- `NftClient` - Handle non-fungible tokens
87+
- `SmartContractClient` - Deploy and interact with smart contracts
88+
- `TopicClient` - Create and manage messaging topics
89+
90+
### 2. hiero-enterprise-spring
91+
**Purpose**: Spring Boot integration
92+
93+
**Key Components**:
94+
- `@EnableHiero` annotation
95+
- Auto-configuration classes
96+
- Spring Boot properties support
97+
98+
### 3. hiero-enterprise-microprofile
99+
**Purpose**: MicroProfile integration (for Quarkus, Helidon, etc.)
100+
101+
### 4. Sample Applications
102+
**Purpose**: Working examples showing how to use the library
103+
104+
## Core Concepts
105+
106+
### 1. Operator Account
107+
The **operator account** is the account that pays for all transactions. Think of it as your "service account" that funds all operations.
108+
109+
```java
110+
// Configuration
111+
spring.hiero.accountId=0.0.12345678
112+
spring.hiero.privateKey=your-private-key
113+
```
114+
115+
### 2. Clients
116+
Each client provides a specific set of blockchain operations:
117+
118+
```java
119+
@Autowired
120+
private AccountClient accountClient; // Account operations
121+
@Autowired
122+
private FileClient fileClient; // File operations
123+
@Autowired
124+
private TokenClient tokenClient; // Token operations
125+
```
126+
127+
### 3. Transactions vs Queries
128+
- **Transactions**: Modify the blockchain state (create account, transfer tokens)
129+
- **Queries**: Read data from the blockchain (get balance, read file)
130+
131+
## How Everything Works Together
132+
133+
### 1. Application Startup
134+
```java
135+
@SpringBootApplication
136+
@EnableHiero // ← This is the magic!
137+
public class Application {
138+
public static void main(String[] args) {
139+
SpringApplication.run(Application.class, args);
140+
}
141+
}
142+
```
143+
144+
**What happens when you start the application:**
145+
146+
1. **Spring Boot starts** and looks for `@EnableHiero`
147+
2. **Auto-configuration kicks in** (`HieroAutoConfiguration`)
148+
3. **Configuration is loaded** from `application.properties`
149+
4. **HieroContext is created** with your account details
150+
5. **All clients are created** and injected into your beans
151+
6. **Your application is ready** to use blockchain features!
152+
153+
### 2. Making a Blockchain Call
154+
```java
155+
@Service
156+
public class MyService {
157+
@Autowired
158+
private AccountClient accountClient;
159+
160+
public void createAccount() {
161+
Account newAccount = accountClient.createAccount();
162+
System.out.println("Created account: " + newAccount.accountId());
163+
}
164+
}
165+
```
166+
167+
**What happens when you call `createAccount()`:**
168+
169+
1. **AccountClient** receives the request
170+
2. **ProtocolLayerClient** creates the transaction
171+
3. **Hedera SDK** sends transaction to network
172+
4. **Network** processes and confirms transaction
173+
5. **Response** returns with new account details
174+
6. **Account object** is created and returned
175+
176+
### 3. Data Flow Example
177+
```
178+
Your Code → AccountClient → ProtocolLayerClient → Hedera SDK → Hiero Network
179+
↑ ↓
180+
└────────────── Account Object ←──────────────────────────────┘
181+
```

0 commit comments

Comments
 (0)