Skip to content

Commit dea60c8

Browse files
AkramBitaradecaro
AkramBitar
authored and
adecaro
committed
Add more docs to dlognogh_ benchmark tests
Signed-off-by: AkramBitar <akram@il.ibm.com>
1 parent 57b15b2 commit dea60c8

4 files changed

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

0 commit comments

Comments
 (0)