Skip to content

Commit 9de5e78

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

4 files changed

Lines changed: 452 additions & 2 deletions

File tree

‎docs/benchmark/benchmark.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,14 @@
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+
- [ZKAT DLog Regression Tests](core/dlognogh/dlognogh_regression.md) - Backwards compatibility testing
17+
18+
### Services
1119

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

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

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

3+
> **Related Documentation:**
4+
> - [Testing Architecture](./dlognogh_architecture.md) - Understanding the test layers
5+
> - [Regression Tests](./dlognogh_regression.md) - Backwards compatibility testing
6+
37
Packages with benchmark tests:
48

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

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

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

0 commit comments

Comments
 (0)