Skip to content

Commit 46197d8

Browse files
authored
Merge branch 'main' into yveshauser/formal-spec-docs
2 parents 2b90c28 + cc71334 commit 46197d8

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

96 files changed

+39561
-1518
lines changed

.github/workflows/ci.yaml

+92-33
Original file line numberDiff line numberDiff line change
@@ -8,41 +8,40 @@ on:
88
pull_request:
99
push:
1010
branches:
11-
- main
11+
- main
1212
jobs:
13-
1413
typecheck:
1514
name: Typecheck specification
1615
runs-on: ubuntu-22.04
1716
steps:
18-
- name: 📥 Checkout repository
19-
uses: actions/checkout@v4
20-
- name: 💾 Cache Nix store
21-
uses: actions/[email protected]
22-
id: nix-cache
23-
with:
24-
path: /tmp/nixcache
25-
key: ${{ runner.os }}-nix-typecheck-${{ hashFiles('flake.lock') }}
26-
restore-keys: ${{ runner.os }}-nix-typecheck-
27-
- name: 🛠️ Install Nix
28-
uses: cachix/install-nix-action@v21
29-
with:
30-
nix_path: nixpkgs=channel:nixos-unstable
31-
install_url: https://releases.nixos.org/nix/nix-2.10.3/install
32-
extra_nix_config: |
33-
allowed-uris = ${{ env.ALLOWED_URIS }}
34-
trusted-public-keys = ${{ env.TRUSTED_PUBLIC_KEYS }}
35-
substituters = ${{ env.SUBSTITUTERS }}
36-
experimental-features = nix-command flakes
37-
- name: 💾➤ Import Nix store cache
38-
if: "steps.nix-cache.outputs.cache-hit == 'true'"
39-
run: "nix-store --import < /tmp/nixcache"
40-
- name: 🏗️ Build specification
41-
run: |
42-
nix build --show-trace --accept-flake-config .#leiosSpec
43-
- name: ➤💾 Export Nix store cache
44-
if: "steps.nix-cache.outputs.cache-hit != 'true'"
45-
run: "nix-store --export $(find /nix/store -maxdepth 1 -name '*-*') > /tmp/nixcache"
17+
- name: 📥 Checkout repository
18+
uses: actions/checkout@v4
19+
- name: 💾 Cache Nix store
20+
uses: actions/[email protected]
21+
id: nix-cache
22+
with:
23+
path: /tmp/nixcache
24+
key: ${{ runner.os }}-nix-typecheck-${{ hashFiles('flake.lock') }}
25+
restore-keys: ${{ runner.os }}-nix-typecheck-
26+
- name: 🛠️ Install Nix
27+
uses: cachix/install-nix-action@v21
28+
with:
29+
nix_path: nixpkgs=channel:nixos-unstable
30+
install_url: https://releases.nixos.org/nix/nix-2.10.3/install
31+
extra_nix_config: |
32+
allowed-uris = ${{ env.ALLOWED_URIS }}
33+
trusted-public-keys = ${{ env.TRUSTED_PUBLIC_KEYS }}
34+
substituters = ${{ env.SUBSTITUTERS }}
35+
experimental-features = nix-command flakes
36+
- name: 💾➤ Import Nix store cache
37+
if: "steps.nix-cache.outputs.cache-hit == 'true'"
38+
run: "nix-store --import < /tmp/nixcache"
39+
- name: 🏗️ Build specification
40+
run: |
41+
nix build --show-trace --accept-flake-config .#leiosSpec
42+
- name: ➤💾 Export Nix store cache
43+
if: "steps.nix-cache.outputs.cache-hit != 'true'"
44+
run: "nix-store --export $(find /nix/store -maxdepth 1 -name '*-*') > /tmp/nixcache"
4645

4746
compile:
4847
name: Build Haskell packages with GHC ${{ matrix.ghc-version }} on ${{ matrix.os }}
@@ -51,7 +50,7 @@ jobs:
5150
fail-fast: false
5251
matrix:
5352
os: [ubuntu-22.04]
54-
ghc-version: ['9.8']
53+
ghc-version: ["9.8"]
5554

5655
steps:
5756
- uses: actions/checkout@v4
@@ -62,7 +61,7 @@ jobs:
6261
with:
6362
ghc-version: ${{ matrix.ghc-version }}
6463
# Defaults, added for clarity:
65-
cabal-version: 'latest'
64+
cabal-version: "latest"
6665
cabal-update: true
6766
- name: Install libraries
6867
run: sudo apt-get install -y libpango1.0-dev libgtk-3-dev
@@ -102,6 +101,20 @@ jobs:
102101
- name: Run tests
103102
run: cabal test all
104103

104+
rs-compile:
105+
name: Check Rust packages
106+
runs-on: ubuntu-22.04
107+
steps:
108+
- uses: actions/checkout@v4
109+
- name: Check Rust packages compilation
110+
working-directory: sim-rs
111+
run: |
112+
cargo check
113+
if [ $? -ne 0 ]; then
114+
echo "Cargo check failed"
115+
exit 1
116+
fi
117+
105118
fourmolu-check:
106119
name: Check Haskell sources with fourmolu
107120
runs-on: ubuntu-22.04
@@ -112,6 +125,52 @@ jobs:
112125
with:
113126
version: "0.15.0.0"
114127

128+
generate-diagrams:
129+
name: Generate D2 Diagrams
130+
runs-on: ubuntu-22.04
131+
permissions:
132+
contents: write
133+
steps:
134+
- name: 📥 Checkout repository
135+
uses: actions/checkout@v4
136+
with:
137+
ref: ${{ github.head_ref || github.ref_name }}
138+
139+
- name: Install D2
140+
run: |
141+
curl -fsSL https://d2lang.com/install.sh | sh -s --
142+
d2 --version
143+
144+
- name: Generate PNG files
145+
run: |
146+
find . -name "*.d2" -type f -exec sh -c '
147+
for file do
148+
output_file="${file%.d2}.png"
149+
echo "Converting $file to $output_file"
150+
d2 "$file" "$output_file"
151+
done
152+
' sh {} +
153+
154+
- name: Check for changes
155+
id: changes
156+
run: |
157+
git add *.png
158+
if git diff --staged --quiet; then
159+
echo "No changes to commit"
160+
echo "has_changes=false" >> $GITHUB_OUTPUT
161+
else
162+
echo "Changes detected"
163+
echo "has_changes=true" >> $GITHUB_OUTPUT
164+
fi
165+
166+
- name: Commit and push changes
167+
if: steps.changes.outputs.has_changes == 'true'
168+
run: |
169+
git config --global user.name 'github-actions[bot]'
170+
git config --global user.email 'github-actions[bot]@users.noreply.github.com'
171+
git commit -m "Auto-generate diagram PNGs [skip ci]"
172+
git push origin HEAD:${{ github.head_ref || github.ref_name }}
173+
115174
build-docusaurus:
116175
runs-on: ubuntu-22.04
117176
steps:
@@ -122,7 +181,7 @@ jobs:
122181
uses: actions/setup-node@v4
123182
with:
124183
node-version: 20
125-
cache: 'yarn'
184+
cache: "yarn"
126185
cache-dependency-path: site/yarn.lock
127186

128187
- name: 📦 Install dependencies

Logbook.md

+96
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,107 @@
11
# Leios logbook
22

3+
## 2024-12-13
4+
5+
### Haskell simulation
6+
7+
- Merged leios visualizations on `main`.
8+
- P2P visualization improvements:
9+
* Block types are differentiated by shapes, and pipelines by color.
10+
* Charting diffusion latency of each block type.
11+
* TODO: chart CPU usage.
12+
- Reworked generation of EBs and Votes to handle `>= 1` frequencies
13+
like IBs (except max 1 EB per pipeline per node).
14+
- Visualizations helped with discovering and fixing some modeling errors.
15+
16+
## 2024-12-12
17+
18+
### Analysis of vote size and ALBA certificates
19+
20+
Keeping votes small is critical to having certificates that fit on a Praos ranking block. In the [draft technical report](docs/technical-report-1.md#structure-of-votes) we have estimated the minimum possible size for votes using either ephemeral keys or KES:
21+
22+
| Method | Common to all votes for a given EB | Specific to individual vote | Total |
23+
| -------------- | ---------------------------------: | --------------------------: | ----- |
24+
| Ephemeral keys | 32 B | 146 B | 178 B |
25+
| KES complete | 64 B | 498 B | 562 B |
26+
27+
The KES votes are a challenge for ALBA because they would require a 90% quorum, meaning that an adversary with more than 10% of the stake could prevent voting.
28+
29+
The CPU time estimate that we have benchmarked for the "centralized telescope" version of ALBA are favorable, however:
30+
31+
- Prove: 9.0 ms
32+
- Verify: 85 μs
33+
34+
### Review Session 1 - Formal Specification
35+
36+
Team reviewed formal specification and further provided input for improvements.
37+
38+
### Rust simulation
39+
40+
Merged virtual time branch. The rust simulation logic is now decoupled from wall clock time.
41+
42+
Experimented with using netsim for the networking layer again. It works, but we currently have to simulate network activity 1ms at a time, making the simulation slow. Waiting for the netsim API to expose a "lower bound" of how long to wait until another message will arrive.
43+
44+
## 2024-12-11
45+
46+
### Discussion with IOG SRE for nodes
47+
48+
We met with IOG's SRE for node operations to discuss cloud engineering aspects of the current Cardano node deployments that might be relevant for Leios.
49+
50+
- We have information now about what VM sizes are for nodes and each relay.
51+
- We also have access to the grafana dashboards for examining mainnet and other nodes.
52+
- They've created custom grafana queries so we can see I/O, network, and disk usage.
53+
54+
Recommendations:
55+
56+
1. Update the cost calculator so that it has pre-defined cost defaults for several cases such as on-demand VMs, bare metal, etc.
57+
2. Alter the cost calculator to include a specified amount of "free" IOPS and network egress that are included with the selected base VM and/or disks.
58+
3. Compare the Praos telemetry on IOG's mainnet nodes to the output of the cost calculator when Leios is turned off.
59+
60+
## 2024-12-10
61+
62+
### Threat model
63+
64+
The technical report now contains a draft section on [the Leios threat mode](docs/technical-report-1.md#threat-model) detailing 25 hypothetical threats. The general types are . . .
65+
66+
- Grinding the VRF to obtain an advantage in Leios sortition
67+
- Equivocating IBs, EBs, or RBs
68+
- Declining to create IBs, EBs, or votes
69+
- Manipulating the content of IBs or EBs
70+
- Sending invalid txs, IBs, EBs, or certificates
71+
- Abusing the sync protocol
72+
- Delaying diffusion of IBs, EBs, or votes
73+
- Submitting invalid, conflicting, or duplicate txs
74+
75+
The protocol already fully or partially mitigates many of these, but they are listed for completeness and eventual discussion in the Leios CIP. Others are a subject of ongoing research.
76+
77+
The general impact of such attacks varies:
78+
79+
- Resource burden on nodes
80+
- Lower throughput
81+
- Increased latency
82+
- Manipulation of dapps or oracles
83+
84+
### Summary of mainnet data available
85+
86+
- [These slides](https://docs.google.com/presentation/d/1Iy2Vu3jZMsHFrvqmiM8urK9EVXbYJW0knb5XQ7w2tZE/edit?usp=sharing) summarize data we have available for topology, block propagation, transaction delays, etc.
87+
- Will can reformat data we need for our simulations, so we don't end up with inconsistent input data sets.
88+
- We will use the [beta-distribution fit](docs/technical-report-1.md#stake-distribution) for representing the unevenness of the stake distribution in our simulations.
89+
90+
91+
### Rust simulation
92+
93+
Generated new test data set to match geographical distribution of mainnet nodes. In this dataset, nodes belong to a region (and have an explicit region tag) and are physically clustered near other nodes in that region.
94+
395
## 2024-12-09
496

597
### Nix development environment
698

799
We previously had a `nix develop` environment for the Haskell simulation, but this was removed as the Haskell package evolved. Instead of re-nixifying this repository, I created a separate [ouroboros-leios.env](https://github.com/functionally/ouroboros-leios.env) repository where one can open a `nix develop` with the correct Haskell compiler and dependencies.
8100

101+
### Rust simulation
102+
103+
Roland has written a fully virtual clock. When finished, this will decouple the sim's performance from the wall clock, and ensure traffic timings are still correct even when there are too many messages to simulate in real time.
104+
9105
## 2024-12-06
10106

11107
### ΔQ

0 commit comments

Comments
 (0)