Docs review: Developer documentation

[olgahryniuk]

This pull request suggests edits to all sections under 'Developer documentation'.

@ch1bo, just one request, please: can you rename the 'Architecture Decision Records' title to 'Architectural decision records' for consistency with other titles? We won't be changing anything in the actual ADR section.

[github-actions]

Transaction costs

Sizes and execution budgets for Hydra protocol transactions. Note that unlisted parameters are currently using arbitrary values and results are not fully deterministic and comparable to previous runs.

Metadata
Generated at	2024-07-22 07:53:12.662341087 UTC
Max. memory units	14000000
Max. CPU units	10000000000
Max. tx size (kB)	16384

Script summary

Name	Hash	Size (Bytes)
νInitial	e6685648e63ab510b49d2ce632c570d2ef53f44f3cbdf82ed553906c	4081
νCommit	fce3b967fb72f4a3be8dfa30defe413258ff453e5d32d6752d83f9cf	2060
νHead	10a116037de398d6b0721152336d602f0ea653eb3dfe540d5da63fe4	9367
μHead	4f93fdfeda690e005d3f5a180208edd3f65ddd0892466ad7f4dd678b*	4236

• The minting policy hash is only usable for comparison. As the script is parameterized, the actual script is unique per head.

Init transaction costs

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	4817	5.61	2.21	0.42
2	5018	7.18	2.84	0.45
3	5219	8.61	3.40	0.47
5	5622	11.21	4.43	0.52
10	6628	18.24	7.22	0.64
58	16275	84.23	33.31	1.79

Commit transaction costs

This uses ada-only outputs for better comparability.

UTxO	Tx size	% max Mem	% max CPU	Min fee ₳
1	559	9.25	3.68	0.28
2	745	11.94	4.93	0.32
3	937	14.70	6.20	0.35
5	1304	20.44	8.83	0.44
10	2241	36.05	15.86	0.65
26	5246	98.14	42.75	1.48

CollectCom transaction costs

Parties	UTxO (bytes)	Tx size	% max Mem	% max CPU	Min fee ₳
1	57	548	14.13	5.69	0.33
2	114	654	22.49	9.14	0.43
3	170	764	32.99	13.51	0.55
4	226	874	42.94	17.79	0.66
5	284	984	56.83	23.61	0.82
6	339	1099	69.83	29.24	0.97
7	393	1205	88.13	36.94	1.18

Close transaction costs

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	603	8.04	4.52	0.27
2	685	8.36	5.25	0.29
3	996	10.20	7.31	0.33
5	1266	11.66	9.46	0.37
10	1987	15.75	15.32	0.48
50	8017	49.94	62.73	1.36

Contest transaction costs

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	610	8.40	4.65	0.28
2	753	9.08	5.70	0.30
3	953	10.15	7.10	0.33
5	1156	11.21	8.89	0.36
10	2133	16.87	16.14	0.50
50	8230	51.90	64.30	1.40

Abort transaction costs

There is some variation due to the random mixture of initial and already committed outputs.

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	4707	16.52	7.21	0.54
2	4758	25.97	11.34	0.65
3	4997	40.81	18.09	0.83
4	5000	51.08	22.43	0.94
5	5156	72.00	31.87	1.19
6	5424	97.34	43.26	1.49

FanOut transaction costs

Involves spending head output and burning head tokens. Uses ada-only UTxO for better comparability.

Parties	UTxO	UTxO (bytes)	Tx size	% max Mem	% max CPU	Min fee ₳
5	0	0	4650	7.71	3.24	0.44
5	1	57	4684	9.14	4.07	0.46
5	5	285	4821	13.41	6.80	0.52
5	10	569	4989	18.41	10.05	0.59
5	20	1140	5330	29.99	17.24	0.75
5	30	1707	5669	41.37	24.35	0.91
5	40	2279	6011	52.36	31.29	1.06
5	50	2845	6347	63.37	38.24	1.22
5	82	4671	7438	99.23	60.77	1.72

End-to-end benchmark results

This page is intended to collect the latest end-to-end benchmark results produced by Hydra's continuous integration (CI) system from the latest master code.

Please note that these results are approximate as they are currently produced from limited cloud VMs and not controlled hardware. Rather than focusing on the absolute results, the emphasis should be on relative results, such as how the timings for a scenario evolve as the code changes.

Generated at 2024-07-22 07:55:41.147991267 UTC

Baseline Scenario

Number of nodes	1
Number of txs	3000
Avg. Confirmation Time (ms)	4.196579952
P99	7.7199148199999605ms
P95	5.1162855ms
P50	4.029676ms
Number of Invalid txs	0

Three local nodes

Number of nodes	3
Number of txs	9000
Avg. Confirmation Time (ms)	21.560594400
P99	90.73409965000026ms
P95	29.77860769999999ms
P50	19.4300805ms
Number of Invalid txs	0

[github-actions]

Test Results

437 tests   425 ✅  14m 52s ⏱️
143 suites   12 💤
  5 files      0 ❌

Results for commit c64d2a0.

♻️ This comment has been updated with latest results.

[ch1bo]

@olgahryniuk ADRs are capitalized because its an acronym. Shall we add "(ADR)"?

[olgahryniuk]

@ch1bo, I don't think we need to add 'ADRs' to the title (it will be too long). Let's leave it as is then. Many thanks.

[locallycompact]

@olgahryniuk Could you fix the conflicts here and on #1498 please so I can merge them?

[olgahryniuk]

@locallycompact, I think I managed to address the merge conflicts. Can you please double-check if everything is okay?