add GET /snapshot/seen endpoint

[ffakenz]

In a situation where the head is not reaching consensus, this endpoint helps identify the peer not cooperating: missing to sign the current snapshot in flight (emit AckSn) and preventing its confirmation.

This can happen in multiple situations, such as the one described in issue #1773, often due to a peer going offline or falling out of sync because of differences in its local ledger state, configuration, or node version. This leads to conflicting views on UTxO availability, blocking further snapshot confirmation, and effectively stalling the Hydra head.

---

• CHANGELOG updated or not needed
• Documentation updated or not needed
• Haddocks updated or not needed
• No new TODOs introduced or explained herafter

[github-actions]

Transaction cost differences

Script summary

Name	Size (Bytes)
νInitial	-
νCommit	-
νHead	-
μHead	-
νDeposit	-

Init transaction costs

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	-	-	-	-
2	-	-	-	-
3	-	-	-	-
5	-	-	-	-
10	-	-	-	-
40	-	-	-	-

Commit transaction costs

UTxO	Tx size	% max Mem	% max CPU	Min fee ₳
1	-	-	-	-
2	-	-	-	-
3	-	-	-	-
5	-	-	-	-
10	-	-	-	-
54	-	-	-	-

CollectCom transaction costs

Parties	UTxO (bytes)	Tx size	% max Mem	% max CPU	Min fee ₳
1	-	-	-	-	-
2	-	-	-	-	-
3	-	-	-	-	-
4	-	-	-	-	-
5	-	-	-	-	-
6	-	-	-	-	-
7	-	-	-	-	-
8	-	-	-	-	-

Cost of Increment Transaction

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	-	$${\color{green}-0.39}$$	$${\color{green}-0.09}$$	-
2	-	-	-	-
3	-	+0.39	+0.09	-
5	-	$${\color{green}-0.39}$$	$${\color{green}-0.09}$$	-
10	-	-	-	-
37	-	-	-	-

Cost of Decrement Transaction

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	-	-	-	-
2	-	-	-	-
3	-	-	-	-
5	-	-	-	-
10	-	-	-	-
40	-	-	-	-

Close transaction costs

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	-	-	-	-
2	-	-	-	-
3	-	-	-	-
5	-	-	-	-
10	-	-	-	-
34	-	-	-	-

Contest transaction costs

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	-	-	-	-
2	-	-	-	-
3	-	-	-	-
5	-	-	-	-
10	-	-	-	-
27	-	-	-	-

FanOut transaction costs

UTxO, Parties	UTxO (bytes)	Tx size	% max Mem	% max CPU	Min fee ₳
(0, 10)	-	-	-	-	-
(1, 10)	-	-	-	-	-
(5, 10)	-	-	-	-	-
(10, 10)	-	-	-	-	-
(20, 10)	-	-	-	-	-
(37, 10)	-	-	-	-	-

[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	2025-03-13 10:57:49.687213865 UTC
Max. memory units	14000000
Max. CPU units	10000000000
Max. tx size (kB)	16384

Script summary

Name	Hash	Size (Bytes)
νInitial	c8a101a5c8ac4816b0dceb59ce31fc2258e387de828f02961d2f2045	2652
νCommit	61458bc2f297fff3cc5df6ac7ab57cefd87763b0b7bd722146a1035c	685
νHead	0e35115a2c7c13c68ecd8d74e4987c04d4539e337643be20bb3274bd	14756
μHead	57166715eadb8d3135964325c016eea546c21e1c0aae974ca67df9a5*	5541
νDeposit	ae01dade3a9c346d5c93ae3ce339412b90a0b8f83f94ec6baa24e30c	1102

• 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	6093	10.80	3.35	0.53
2	6295	13.44	4.18	0.57
3	6493	15.71	4.88	0.60
5	6898	19.98	6.17	0.66
10	7903	30.97	9.53	0.82
40	13935	98.61	30.29	1.78

Commit transaction costs

This uses ada-only outputs for better comparability.

UTxO	Tx size	% max Mem	% max CPU	Min fee ₳
1	561	2.44	1.16	0.20
2	743	3.38	1.73	0.22
3	920	4.36	2.33	0.24
5	1279	6.41	3.60	0.28
10	2171	12.13	7.25	0.40
54	10076	98.61	68.52	1.88

CollectCom transaction costs

Parties	UTxO (bytes)	Tx size	% max Mem	% max CPU	Min fee ₳
1	57	525	25.67	7.41	0.43
2	113	636	33.87	9.75	0.52
3	169	747	44.51	12.68	0.63
4	227	858	54.79	15.58	0.74
5	281	969	62.70	17.81	0.83
6	337	1081	77.08	21.67	0.98
7	394	1192	88.26	24.70	1.09
8	451	1303	89.59	25.51	1.12
9	505	1418	98.12	27.90	1.21

Cost of Increment Transaction

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	1827	25.42	8.32	0.50
2	1935	26.99	9.47	0.52
3	2145	29.62	11.03	0.56
5	2370	32.89	13.35	0.62
10	3136	42.07	19.68	0.77
39	7339	97.28	56.72	1.67

Cost of Decrement Transaction

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	606	23.99	7.61	0.43
2	764	25.31	8.66	0.45
3	871	26.44	9.60	0.47
5	1278	34.32	13.11	0.58
10	2092	44.30	19.19	0.74
39	6267	99.14	53.64	1.61

Close transaction costs

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	682	30.95	9.69	0.50
2	837	31.02	10.45	0.51
3	945	34.83	12.20	0.56
5	1247	39.16	14.95	0.63
10	1988	50.26	21.83	0.80
35	5614	96.35	53.27	1.56

Contest transaction costs

Parties	Tx size	% max Mem	% max CPU	Min fee ₳
1	675	35.99	11.01	0.55
2	832	38.15	12.33	0.58
3	983	40.94	13.92	0.62
5	1258	45.41	16.59	0.69
10	2004	57.11	23.58	0.87
27	4280	95.04	46.36	1.44

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	5988	28.36	9.35	0.71
2	6113	37.46	12.36	0.81
3	6167	43.38	14.24	0.87
4	6397	57.75	19.07	1.04
5	6359	61.00	19.99	1.07
6	6564	75.30	24.78	1.23
7	6858	88.16	29.10	1.37
8	6857	95.30	31.45	1.45

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 ₳
10	1	57	6125	21.33	7.13	0.64
10	5	284	6260	29.85	10.44	0.74
10	30	1708	7111	84.03	31.40	1.37
10	36	2048	7314	96.35	36.21	1.51

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 2025-03-13 11:00:52.517142005 UTC

Baseline Scenario

Number of nodes	1
Number of txs	300
Avg. Confirmation Time (ms)	4.433207496
P99	6.615651269999986ms
P95	5.2960843ms
P50	4.250527ms
Number of Invalid txs	0

Memory data

Time	Used	Free
2025-03-13 10:59:32.250710503 UTC	949M	6133M
2025-03-13 10:59:37.250673299 UTC	1038M	6006M
2025-03-13 10:59:42.250600617 UTC	1035M	6008M
2025-03-13 10:59:47.250576351 UTC	1036M	6008M
2025-03-13 10:59:52.250579924 UTC	1039M	6004M
2025-03-13 10:59:57.250590612 UTC	1039M	6003M

Three local nodes

Number of nodes	3
Number of txs	900
Avg. Confirmation Time (ms)	33.868931333
P99	76.98774557999998ms
P95	62.20330924999999ms
P50	29.5756765ms
Number of Invalid txs	0

Memory data

Time	Used	Free
2025-03-13 11:00:10.505061831 UTC	954M	6098M
2025-03-13 11:00:15.506028041 UTC	1208M	5840M
2025-03-13 11:00:20.507631447 UTC	1266M	5723M
2025-03-13 11:00:25.5054424 UTC	1270M	5668M
2025-03-13 11:00:30.505397145 UTC	1280M	5658M
2025-03-13 11:00:35.505426562 UTC	1279M	5658M
2025-03-13 11:00:40.505351148 UTC	1279M	5658M
2025-03-13 11:00:45.505397385 UTC	1279M	5657M
2025-03-13 11:00:50.505379981 UTC	1283M	5653M

[ch1bo]

In principle this looks fine.

The whole projection business becomes unwieldy and I think we should depart from it (we are storing multiple read models in TVars while we could just have a single one for the whole HeadState).

The API path is a bit odd as seen is not really a part of /snapshot and is a different part of the HeadState. The example API of ADR25 (proposed) would suggest a better path would be /head/ledger/seen or /ledger/seen. (There may be even better resource names than ledger and we should also update the ADR)

[noonio]

Looks great; thanks for putting this together.

I propose to change the API path to

/head/last-seen-snapshot

Aside from that, good to merge (once build issues fixed!)