Skip to content

Commit 00697ca

Browse files
Rozerxshashankadecaro
Rozerxshashank
authored and
adecaro
committed
docs: add fabtoken benchmark architecture guide
Signed-off-by: Shashank <yshashank959@gmail.com>
1 parent 2d77a8b commit 00697ca

2 files changed

Lines changed: 322 additions & 0 deletions

File tree

‎docs/drivers/benchmark/core/fabtoken/fabtoken.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Fabtoken Benchmarks
2+
3+
This document provides an overview of the performance benchmarks for the Fabtoken driver in the Fabric Token SDK.
4+
5+
> **Related Documentation:**
6+
> - [Testing Architecture](./fabtoken_architecture.md) - Understanding the test layers
7+
8+
## Overview
9+
10+
The Fabtoken benchmarks measure the performance of token operations (Issue, Transfer, and Validation) at different abstraction layers. Unlike the ZKAT DLog driver, Fabtoken does not use complex zero-knowledge proofs, making its operations significantly faster and simpler.
11+
12+
## Benchmark Packages
13+
14+
The following packages contain benchmark tests for Fabtoken:
15+
16+
- `token/core/fabtoken/v1`:
17+
- **Layer 3 (Service)**: `BenchmarkTransferServiceTransfer`, `BenchmarkIssueServiceIssue`
18+
- **Layer 2 (Action Generation)**: `BenchmarkSender`, `BenchmarkIssuer`
19+
- **Layer 2 (Action Verification)**: `BenchmarkVerificationSenderProof`, `BenchmarkProofVerificationIssuer`
20+
- **Layer 1 (Core)**: `BenchmarkTransferProofGeneration`
21+
- `token/core/fabtoken/v1/validator`:
22+
- **Layer 3 (Service)**: `BenchmarkValidatorTransfer`, `BenchmarkValidatorIssue`
23+
24+
## Parameters
25+
26+
Fabtoken benchmarks support the same programmatic parameter system as other drivers:
27+
28+
- **NumInputs**: Number of input tokens (for Transfer).
29+
- **NumOutputs**: Number of output tokens (for Issue and Transfer).
30+
31+
These are controlled via the `benchmark` package and can be customized in the test code or via flags if implemented in the future (currently using defaults from `GenerateCasesWithDefaults`).
32+
33+
## How to Run
34+
35+
### Run Service Layer Benchmarks
36+
```bash
37+
# Transfer Service
38+
go test ./token/core/fabtoken/v1 -bench=BenchmarkTransferServiceTransfer -benchmem -run=^$
39+
40+
# Issue Service
41+
go test ./token/core/fabtoken/v1 -bench=BenchmarkIssueServiceIssue -benchmem -run=^$
42+
```
43+
44+
### Run Action Layer Benchmarks
45+
```bash
46+
# Transfer Action Generation
47+
go test ./token/core/fabtoken/v1 -bench=BenchmarkSender -benchmem -run=^$
48+
49+
# Issue Action Generation
50+
go test ./token/core/fabtoken/v1 -bench=BenchmarkIssuer -benchmem -run=^$
51+
```
52+
53+
### Run Validator Benchmarks
54+
```bash
55+
go test ./token/core/fabtoken/v1/validator -bench=BenchmarkValidatorTransfer -benchmem -run=^$
56+
go test ./token/core/fabtoken/v1/validator -bench=BenchmarkValidatorIssue -benchmem -run=^$
57+
```
58+
59+
## Parallel Benchmarking
60+
61+
Most benchmarks include parallel variants to measure performance under concurrent load:
62+
63+
- **Built-in Parallelism**: `BenchmarkParallelSender`, `BenchmarkVerificationParallelSenderProof`
64+
- **Custom Parallel Framework**: `TestParallelBenchmarkTransferServiceTransfer`, `TestParallelBenchmarkValidatorTransfer`, etc.
65+
66+
To run the custom parallel benchmarks (using `*testing.T`):
67+
```bash
68+
go test ./token/core/fabtoken/v1 -run=TestParallelBenchmarkTransferServiceTransfer -v
69+
```
70+
71+
## Understanding Results
72+
73+
The benchmarks report:
74+
- `ns/op`: Time taken per operation.
75+
- `B/op`: Memory allocated per operation.
76+
- `allocs/op`: Number of memory allocations per operation.
77+
78+
Lower values indicate better performance. Since Fabtoken uses standard cryptographic signatures (like ECDSA or RSA) instead of ZK proofs, you should expect much lower `ns/op` compared to the DLog driver.

‎docs/drivers/benchmark/core/fabtoken/fabtoken_architecture.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# Fabtoken Testing Architecture
2+
3+
This document explains the testing architecture for the Fabtoken implementation in the Fabric Token SDK.
4+
5+
> **Related Documentation:**
6+
> - [Running Benchmarks](./fabtoken.md) - How to run performance benchmarks
7+
8+
## Overview
9+
10+
The Fabtoken tests are organized in a **layered architecture** that mirrors the **code abstraction levels**. Each layer represents a different level of the software stack - from core operations to high-level service APIs.
11+
12+
## Architecture Layers
13+
14+
Each layer represents a different **code abstraction level**.
15+
16+
```
17+
┌─────────────────────────────────────────────────────────────────┐
18+
│ Layer 3: Service Layer (Highest Abstraction) │
19+
├─────────────────────────────────────────────────────────────────┤
20+
│ Transfer Generation Service │
21+
│ Location: token/core/fabtoken/v1/ │
22+
│ Tests: - BenchmarkTransferServiceTransfer │
23+
│ - TestParallelBenchmarkTransferServiceTransfer │
24+
│ Purpose: End-to-end transfer operation generation with vault, │
25+
│ audit, and metadata handling │
26+
├─────────────────────────────────────────────────────────────────┤
27+
│ Transfer/Issue Validator Service │
28+
│ Location: token/core/fabtoken/v1/validator/ │
29+
│ Tests: - BenchmarkValidatorTransfer │
30+
│ - TestParallelBenchmarkValidatorTransfer │
31+
│ - BenchmarkValidatorIssue │
32+
│ - TestParallelBenchmarkValidatorIssue │
33+
│ Purpose: Token request validation with signatures, business │
34+
│ logic, and format verification │
35+
└─────────────────────────────────────────────────────────────────┘
36+
37+
┌─────────────────────────────────────────────────────────────────┐
38+
│ Layer 2: Action Operations │
39+
├─────────────────────────────────────────────────────────────────┤
40+
│ Transfer Generation (token/core/fabtoken/v1/) │
41+
│ Tests: - BenchmarkSender │
42+
│ - BenchmarkParallelSender │
43+
│ - TestParallelBenchmarkSender │
44+
│ Purpose: Transfer action generation and serialization │
45+
├─────────────────────────────────────────────────────────────────┤
46+
│ Transfer Verification (token/core/fabtoken/v1/) │
47+
│ Tests: - BenchmarkVerificationSenderProof │
48+
│ - BenchmarkVerificationParallelSenderProof │
49+
│ - TestParallelBenchmarkVerificationSenderProof │
50+
│ Purpose: Deserialization and format validation of transfer │
51+
│ actions │
52+
├─────────────────────────────────────────────────────────────────┤
53+
│ Issue Generation (token/core/fabtoken/v1/) │
54+
│ Tests: - BenchmarkIssuer │
55+
│ Purpose: Issue action generation and serialization │
56+
├─────────────────────────────────────────────────────────────────┤
57+
│ Issue Verification (token/core/fabtoken/v1/) │
58+
│ Tests: - BenchmarkProofVerificationIssuer │
59+
│ Purpose: Deserialization and verification of issue actions │
60+
└─────────────────────────────────────────────────────────────────┘
61+
62+
┌─────────────────────────────────────────────────────────────────┐
63+
│ Layer 1: Core Operations (Lowest Abstraction) │
64+
│ Location: token/core/fabtoken/v1/ │
65+
│ Tests: - BenchmarkTransferProofGeneration │
66+
│ - TestParallelBenchmarkTransferProofGeneration │
67+
│ Purpose: Pure transfer action structure generation and │
68+
│ serialization │
69+
└─────────────────────────────────────────────────────────────────┘
70+
```
71+
72+
---
73+
74+
## Layer 1: Core Operations
75+
76+
**Location:** `token/core/fabtoken/v1/`
77+
78+
### Tests
79+
- `BenchmarkTransferProofGeneration`
80+
- `TestParallelBenchmarkTransferProofGeneration`
81+
82+
### Purpose
83+
Pure transfer action generation and serialization. In Fabtoken, since there are no complex zero-knowledge proofs, this layer focuses on the core action structure creation.
84+
85+
### Example Commands
86+
```bash
87+
cd token/core/fabtoken/v1
88+
go test -bench=BenchmarkTransferProofGeneration -benchtime=10s
89+
go test -run=TestParallelBenchmarkTransferProofGeneration -v
90+
```
91+
92+
---
93+
94+
## Layer 2: Action Operations
95+
96+
### Transfer Action Generation
97+
98+
**Location:** `token/core/fabtoken/v1/`
99+
100+
#### Tests
101+
- `BenchmarkSender`
102+
- `BenchmarkParallelSender`
103+
- `TestParallelBenchmarkSender`
104+
105+
#### Purpose
106+
Complete transfer action creation from inputs to serialized output.
107+
108+
#### Example Commands
109+
```bash
110+
cd token/core/fabtoken/v1
111+
go test -bench=BenchmarkSender -benchtime=10s
112+
go test -bench=BenchmarkParallelSender -benchtime=10s
113+
go test -run=TestParallelBenchmarkSender -v
114+
```
115+
116+
### Transfer Action Verification
117+
118+
**Location:** `token/core/fabtoken/v1/`
119+
120+
#### Tests
121+
- `BenchmarkVerificationSenderProof`
122+
- `BenchmarkVerificationParallelSenderProof`
123+
- `TestParallelBenchmarkVerificationSenderProof`
124+
125+
#### Purpose
126+
Deserialization and verification of transfer actions.
127+
128+
#### Example Commands
129+
```bash
130+
cd token/core/fabtoken/v1
131+
go test -bench=BenchmarkVerificationSenderProof -benchtime=10s
132+
go test -bench=BenchmarkVerificationParallelSenderProof -benchtime=10s
133+
go test -run=TestParallelBenchmarkVerificationSenderProof -v
134+
```
135+
136+
### Issue Action Generation
137+
138+
**Location:** `token/core/fabtoken/v1/`
139+
140+
#### Tests
141+
- `BenchmarkIssuer`
142+
143+
#### Purpose
144+
Complete issue action creation from inputs to serialized output.
145+
146+
#### Example Commands
147+
```bash
148+
cd token/core/fabtoken/v1
149+
go test -bench=BenchmarkIssuer -benchtime=10s
150+
```
151+
152+
### Issue Action Verification
153+
154+
**Location:** `token/core/fabtoken/v1/`
155+
156+
#### Tests
157+
- `BenchmarkProofVerificationIssuer`
158+
159+
#### Purpose
160+
Deserialization and verification of issue actions.
161+
162+
#### Example Commands
163+
```bash
164+
cd token/core/fabtoken/v1
165+
go test -bench=BenchmarkProofVerificationIssuer -benchtime=10s
166+
```
167+
168+
---
169+
170+
## Layer 3: Service Layer
171+
172+
The Service Layer provides the highest level of abstraction for complete end-to-end operations through the Service APIs.
173+
174+
### Transfer Generation Service
175+
176+
**Location:** `token/core/fabtoken/v1/`
177+
178+
#### Tests
179+
- `BenchmarkTransferServiceTransfer`
180+
- `TestParallelBenchmarkTransferServiceTransfer`
181+
182+
#### Purpose
183+
Complete end-to-end transfer operation generation through the high-level Transfer Service API.
184+
185+
#### Includes
186+
- Token Loading from vault
187+
- Input Preparation
188+
- Sender Initialization
189+
- Output Processing
190+
- Action Generation and Serialization
191+
- Audit Information collection
192+
193+
#### Example Commands
194+
```bash
195+
cd token/core/fabtoken/v1
196+
go test -bench=BenchmarkTransferServiceTransfer -benchtime=10s
197+
go test -run=TestParallelBenchmarkTransferServiceTransfer -v
198+
```
199+
200+
### Transfer/Issue Validator Service
201+
202+
**Location:** `token/core/fabtoken/v1/validator/`
203+
204+
#### Tests
205+
- `BenchmarkValidatorTransfer`
206+
- `TestParallelBenchmarkValidatorTransfer`
207+
- `BenchmarkValidatorIssue`
208+
- `TestParallelBenchmarkValidatorIssue`
209+
210+
#### Purpose
211+
Complete validation pipeline performance, including all signature and business logic checks.
212+
213+
#### Example Commands
214+
```bash
215+
cd token/core/fabtoken/v1/validator
216+
go test -bench=BenchmarkValidatorTransfer -benchtime=10s
217+
go test -run=TestParallelBenchmarkValidatorTransfer -v
218+
go test -bench=BenchmarkValidatorIssue -benchtime=10s
219+
go test -run=TestParallelBenchmarkValidatorIssue -v
220+
```
221+
222+
---
223+
224+
## Testing Strategy
225+
226+
### Understanding the Layers
227+
228+
Each layer tests a **different code abstraction level independently**:
229+
230+
- **Layer 1** tests the core action structure generation.
231+
- **Layer 2** tests the action creation/verification code.
232+
- **Layer 3** tests the service layer code:
233+
- **Transfer Validator Service**: validation logic
234+
- **Transfer Generation Service**: end-to-end transfer generation
235+
236+
---
237+
238+
## Parallel Testing Variants
239+
240+
Most layers include parallel test variants that run benchmarks concurrently:
241+
- **`Benchmark*Parallel`**: Go's built-in parallel benchmarking (`*testing.B`)
242+
- **`TestParallelBenchmark*`**: Custom parallel benchmarking framework (`*testing.T`)
243+
244+
These help identify concurrency issues and measure performance under load.

0 commit comments

Comments
 (0)