Skip to content

Commit d988edc

Browse files
AkramBitarAkramBitar
committed
Add more docs to dlognogh_ benchmark tests
Signed-off-by: AkramBitar <akram@il.ibm.com>
1 parent c77d427 commit d988edc

3 files changed

Lines changed: 308 additions & 2 deletions

File tree

‎docs/benchmark/benchmark.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,13 @@
77
- [`memcheck`](./../../token/services/benchmark/cmd/memcheck/README.md): Go Pprof Memory Analyzer
88
- [`traceinspector`](./../../token/services/benchmark/cmd/memcheck/README.md): Go Pprof Trace Analyzer
99

10-
## Benchmark
10+
## Benchmarks
11+
12+
### Core Token Drivers
13+
14+
- [ZKAT DLog No Graph-Hiding Benchmarks](core/dlognogh/dlognogh.md) - How to run benchmarks
15+
- [ZKAT DLog Testing Architecture](core/dlognogh/dlognogh_architecture.md) - Understanding the test layers
16+
17+
### Services
1118

12-
- [ZKAT DLog No Graph-Hiding Benchmarks](core/dlognogh/dlognogh.md)
1319
- [Identity Service - Idemix](services/identity/idemix.md)

‎docs/benchmark/core/dlognogh/dlognogh.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# ZKAT DLog No Graph Hiding Benchmarks
22

3+
> **Related Documentation:**
4+
> For understanding the testing architecture and layers, see [dlognogh_architecture.md](./dlognogh_architecture.md)
5+
36
Packages with benchmark tests:
47

58
- `token/core/zkatdlog/nogh/v1/transfer`:

‎docs/benchmark/core/dlognogh/dlognogh_architecture.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
# ZK-ATDLOG Testing Architecture
2+
3+
This document explains the testing architecture for the Zero-Knowledge Anonymous Token Discrete Logarithm (ZK-ATDLOG) implementation in the Fabric Token SDK.
4+
5+
> **Related Documentation:**
6+
> For detailed instructions on how to run these benchmarks, see [dlognogh.md](./dlognogh.md)
7+
8+
## Overview
9+
10+
The ZK-ATDLOG tests are organized in a **layered architecture** that mirrors the **code abstraction levels**. Each layer represents a different level of the software stack - from low-level cryptographic primitives to high-level service APIs.
11+
12+
## Architecture Layers
13+
14+
Each layer represents a different **code abstraction level**.
15+
16+
```
17+
┌─────────────────────────────────────────────────────────────────┐
18+
│ Layer 4: Service Layer (Highest Abstraction) │
19+
│ Location: token/core/zkatdlog/nogh/v1/ │
20+
│ Tests: - BenchmarkTransferServiceTransfer │
21+
│ - TestParallelBenchmarkTransferServiceTransfer │
22+
│ Purpose: End-to-end transfer operation generation with vault, │
23+
│ audit, and metadata handling │
24+
└─────────────────────────────────────────────────────────────────┘
25+
26+
┌─────────────────────────────────────────────────────────────────┐
27+
│ Layer 3: Validator Layer │
28+
│ Location: token/core/zkatdlog/nogh/v1/validator/ │
29+
│ Tests: - BenchmarkValidatorTransfer │
30+
│ - TestParallelBenchmarkValidatorTransfer │
31+
│ Purpose: Transfer validation with signatures, business logic, │
32+
│ and cryptographic verification │
33+
└─────────────────────────────────────────────────────────────────┘
34+
35+
┌─────────────────────────────────────────────────────────────────┐
36+
│ Layer 2: Action Operations │
37+
├─────────────────────────────────────────────────────────────────┤
38+
│ Transfer Generation (token/core/zkatdlog/nogh/v1/transfer/) │
39+
│ Tests: - BenchmarkSender │
40+
│ - BenchmarkParallelSender │
41+
│ - TestParallelBenchmarkSender │
42+
│ Purpose: Transfer action generation and serialization │
43+
├─────────────────────────────────────────────────────────────────┤
44+
│ Transfer Verification (token/core/zkatdlog/nogh/v1/transfer/) │
45+
│ Tests: - BenchmarkVerificationSenderProof │
46+
│ - BenchmarkVerificationParallelSenderProof │
47+
│ - TestParallelBenchmarkVerificationSenderProof │
48+
│ Purpose: Transfer action cryptographic validation & verification│
49+
├─────────────────────────────────────────────────────────────────┤
50+
│ Issue Generation (token/core/zkatdlog/nogh/v1/issue/) │
51+
│ Tests: - BenchmarkIssuer │
52+
│ Purpose: Issue action generation and serialization │
53+
├─────────────────────────────────────────────────────────────────┤
54+
│ Issue Verification (token/core/zkatdlog/nogh/v1/issue/) │
55+
│ Tests: - BenchmarkProofVerificationIssuer │
56+
│ Purpose: Issue action cryptographic verification │
57+
└─────────────────────────────────────────────────────────────────┘
58+
59+
┌─────────────────────────────────────────────────────────────────┐
60+
│ Layer 1: Core Cryptographic Operations (Lowest Abstraction) │
61+
│ Location: token/core/zkatdlog/nogh/v1/transfer/ │
62+
│ Tests: - BenchmarkTransferProofGeneration │
63+
│ - TestParallelBenchmarkTransferProofGeneration │
64+
│ Purpose: Pure transfer ZK proof generation and serialization │
65+
└─────────────────────────────────────────────────────────────────┘
66+
```
67+
68+
---
69+
70+
## Layer 1: Core Cryptographic Operations
71+
72+
**Location:** `token/core/zkatdlog/nogh/v1/transfer/`
73+
74+
### Tests
75+
- `BenchmarkTransferProofGeneration`
76+
- `TestParallelBenchmarkTransferProofGeneration`
77+
78+
### Purpose
79+
Pure zero-knowledge proof generation and serialization for transfer operations. The parallel version runs the same benchmark in multiple goroutines.
80+
81+
### Includes
82+
- ZK proof computation (range proofs, sum proofs, type proofs)
83+
- Proof serialization to bytes
84+
85+
### Example Commands
86+
```bash
87+
cd token/core/zkatdlog/nogh/v1/transfer
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/zkatdlog/nogh/v1/transfer/`
99+
100+
#### Tests
101+
- `BenchmarkSender`
102+
- `BenchmarkParallelSender`
103+
- `TestParallelBenchmarkSender`
104+
105+
#### Purpose
106+
Complete transfer action creation from inputs to serialized output.
107+
108+
**Note:** `BenchmarkParallelSender` is a Go benchmark (uses `*testing.B`), while `TestParallelBenchmarkSender` is a test (uses `*testing.T`) that runs custom benchmarking. Same functionality, different frameworks.
109+
110+
#### Includes
111+
- ZK proof generation (range proofs, sum proofs, type proofs)
112+
- Input token handling
113+
- Output token creation
114+
- Action serialization
115+
116+
#### Example Commands
117+
```bash
118+
cd token/core/zkatdlog/nogh/v1/transfer
119+
go test -bench=BenchmarkSender -benchtime=10s
120+
go test -bench=BenchmarkParallelSender -benchtime=10s
121+
go test -run=TestParallelBenchmarkSender -v
122+
```
123+
124+
### Transfer Action Verification
125+
126+
**Location:** `token/core/zkatdlog/nogh/v1/transfer/`
127+
128+
#### Tests
129+
- `BenchmarkVerificationSenderProof`
130+
- `BenchmarkVerificationParallelSenderProof`
131+
- `TestParallelBenchmarkVerificationSenderProof`
132+
133+
#### Purpose
134+
Deserialization and cryptographic format validation and verification of transfer actions.
135+
136+
#### Includes
137+
- Action deserialization
138+
- ZKP format validation
139+
- ZK proof verification (range proofs, sum proofs, type proofs)
140+
141+
#### Example Commands
142+
```bash
143+
cd token/core/zkatdlog/nogh/v1/transfer
144+
go test -bench=BenchmarkVerificationSenderProof -benchtime=10s
145+
go test -bench=BenchmarkVerificationParallelSenderProof -benchtime=10s
146+
go test -run=TestParallelBenchmarkVerificationSenderProof -v
147+
```
148+
149+
### Issue Action Generation
150+
151+
**Location:** `token/core/zkatdlog/nogh/v1/issue/`
152+
153+
#### Tests
154+
- `BenchmarkIssuer`
155+
156+
#### Purpose
157+
Complete issue action creation from inputs to serialized output.
158+
159+
#### Includes
160+
- ZK proof generation (range proofs, same-type proofs)
161+
- Output token creation
162+
- Action serialization
163+
164+
#### Example Commands
165+
```bash
166+
cd token/core/zkatdlog/nogh/v1/issue
167+
go test -bench=BenchmarkIssuer -benchtime=10s
168+
go test -bench=BenchmarkIssuer -benchmem
169+
go test -bench=BenchmarkIssuer -cpuprofile=cpu.prof
170+
```
171+
172+
### Issue Action Verification
173+
174+
**Location:** `token/core/zkatdlog/nogh/v1/issue/`
175+
176+
#### Tests
177+
- `BenchmarkProofVerificationIssuer`
178+
179+
#### Purpose
180+
Deserialization and cryptographic verification of issue actions.
181+
182+
#### Includes
183+
- Action deserialization
184+
- ZKP format validation
185+
- ZK proof verification (range proofs, same-type proofs)
186+
187+
#### Example Commands
188+
```bash
189+
cd token/core/zkatdlog/nogh/v1/issue
190+
go test -bench=BenchmarkProofVerificationIssuer -benchtime=10s
191+
```
192+
193+
---
194+
195+
## Layer 3: Validator Layer
196+
197+
**Location:** `token/core/zkatdlog/nogh/v1/validator/`
198+
199+
### Tests
200+
- `BenchmarkValidatorTransfer`
201+
- `TestParallelBenchmarkValidatorTransfer`
202+
203+
### Compatibility Tests
204+
- `regression_test.go` (in `validator/regression/`)
205+
206+
### Purpose
207+
Complete validation pipeline performance, including all cryptographic and business logic checks.
208+
209+
### Includes
210+
- Action deserialization
211+
- Token validation
212+
- Signature verification (including auditors)
213+
- Business logic checks (double-spend prevention, balance checks, etc.)
214+
- ZKP format validation
215+
- ZKP verification (range proofs, sum proofs, type proofs)
216+
217+
### Example Commands
218+
```bash
219+
cd token/core/zkatdlog/nogh/v1/validator
220+
go test -bench=BenchmarkValidatorTransfer -benchtime=10s
221+
go test -run=TestParallelBenchmarkValidatorTransfer -v
222+
```
223+
224+
---
225+
226+
## Layer 4: Service Layer
227+
228+
**Location:** `token/core/zkatdlog/nogh/v1/`
229+
230+
### Tests
231+
- `BenchmarkTransferServiceTransfer`
232+
- `TestParallelBenchmarkTransferServiceTransfer`
233+
234+
### Purpose
235+
Complete end-to-end transfer operation generation through the high-level Transfer Service API.
236+
237+
### Includes
238+
- **Token Loading**: Loads input tokens from vault by their IDs, retrieves token data and metadata
239+
- **Input Preparation**: Deserializes loaded tokens, extracts token commitments, metadata, owner information, and prepares upgrade witnesses if needed
240+
- **Sender Initialization**: Creates a Sender instance with prepared inputs, sets up ZK proof generation context
241+
- **Output Processing**: Extracts target values and owners from requested outputs, converts quantities to proper format, detects redeem operations (empty owner)
242+
- **ZK Transfer Generation**: Generates ZK-SNARK transfer proof (range, sum, type proofs), creates output token commitments, produces output metadata with blinding factors
243+
- **Metadata Enrichment**: Adds transfer action metadata attributes, attaches upgrade witnesses to inputs
244+
- **Audit Information**: Collects audit info for all input token owners, prepares transfer input metadata
245+
- **Output Metadata**: Collects audit info for all output recipients, handles redeem case (no recipient), serializes output metadata, creates transfer output metadata
246+
- **Redeem Handling**: Selects authorized issuer for redeem operations, adds issuer to transfer action and metadata
247+
248+
### Excludes
249+
- Action serialization (tested in Layer 2)
250+
- Signature generation
251+
- Network transmission
252+
253+
### Example Commands
254+
```bash
255+
cd token/core/zkatdlog/nogh/v1
256+
go test -bench=BenchmarkTransferServiceTransfer -benchtime=10s
257+
go test -run=TestParallelBenchmarkTransferServiceTransfer -v
258+
```
259+
260+
---
261+
262+
## Testing Strategy
263+
264+
### Understanding the Layers
265+
266+
Each layer tests a **different code abstraction level independently**:
267+
268+
- **Layer 1** tests only the cryptographic proof generation code (`Prover.Prove()`)
269+
- **Layer 2** tests the action creation/verification code (`Sender.GenerateZKTransfer()`, `Verifier.Verify()`)
270+
- **Layer 3** tests the validation logic code (`Validator.VerifyTransfer()`)
271+
- **Layer 4** tests the service layer code (`TransferService.Transfer()`)
272+
273+
**The layers do NOT build on each other** - they test different parts of the codebase at different abstraction levels.
274+
275+
---
276+
277+
## Parallel Testing Variants
278+
279+
Most layers include parallel test variants that run benchmarks concurrently:
280+
- **`Benchmark*Parallel`**: Go's built-in parallel benchmarking (`*testing.B`)
281+
- **`TestParallelBenchmark*`**: Custom parallel benchmarking framework (`*testing.T`)
282+
283+
These help identify concurrency issues and measure performance under load.
284+
285+
---
286+
287+
## Benchmark Parameters
288+
289+
All benchmarks support various configurations:
290+
- **Bits**: 32, 64 (range proof bit sizes)
291+
- **Curves**: BN254, BLS12_381_BBS_GURVY, BLS12_381_BBS_GURVY_FAST_RNG
292+
- **Inputs**: 1, 2, 3 (number of input tokens for transfers)
293+
- **Outputs**: 1, 2, 3 (number of output tokens)
294+
295+
Example with specific parameters:
296+
```bash
297+
go test -bench=BenchmarkSender/bits_32-curve_BN254-in_2-out_2 -benchtime=10s

0 commit comments

Comments
 (0)