input-output-hk · ch1bo · Oct 25, 2025
diff --git a/.github/workflows/leios-design.yaml b/.github/workflows/leios-design.yaml
@@ -0,0 +1,99 @@
+name: "Build Leios Design PDF"
+
+on:
+  pull_request:
+    paths:
+      - "docs/leios-design/**"
+      - "nix/artifacts.nix"
+      - ".github/workflows/leios-design.yaml"
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/leios-design/**"
+      - "nix/artifacts.nix"
+  workflow_dispatch: # Allow manual triggering
+
+permissions:
+  contents: read
+  actions: read
+
+# Prevent redundant workflow runs
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-pdf:
+    name: "Build Leios Design PDF"
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: 🛠️ Install Nix
+        uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            accept-flake-config = true
+            extra-substituters = https://cache.iog.io
+            extra-trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=
+
+      - name: 🗂️ Setup Cachix for IOG cache
+        uses: cachix/cachix-action@v15
+        with:
+          name: iog
+          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+          skipPush: true
+
+      - name: 🏗️ Build PDF using Nix
+        run: |
+          echo "Building Leios Design PDF..."
+          nix build .#leiosDesignPdf -L
+
+          # Verify the PDF was created
+          if [ ! -f result/leios-design.pdf ]; then
+            echo "Error: PDF file was not created"
+            exit 1
+          fi
+
+          # Show file size and info
+          ls -lh result/leios-design.pdf
+          file result/leios-design.pdf
+
+      - name: 📊 Get PDF metadata
+        run: |
+          # Get basic file info
+          echo "PDF file size: $(stat -c%s result/leios-design.pdf) bytes"
+          echo "PDF creation date: $(stat -c%y result/leios-design.pdf)"
+
+          # If pdfinfo is available, show more details
+          if command -v pdfinfo &> /dev/null; then
+            echo "PDF metadata:"
+            pdfinfo result/leios-design.pdf || true
+          fi
+
+      - name: 🚀 Upload PDF artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: leios-design-pdf-${{ github.sha }}
+          path: result/leios-design.pdf
+          if-no-files-found: error
+          retention-days: 30
+
+      - name: 📄 Add PDF info to job summary
+        run: |
+          echo "## 📄 Leios Design PDF Generated" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "✅ Successfully built PDF from markdown source" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**File details:**" >> $GITHUB_STEP_SUMMARY
+          echo "- Size: $(stat -c%s result/leios-design.pdf) bytes" >> $GITHUB_STEP_SUMMARY
+          echo "- Generated: $(date -u '+%Y-%m-%d %H:%M:%S UTC')" >> $GITHUB_STEP_SUMMARY
+          echo "- Commit: \`${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "The PDF is available as a workflow artifact named \`leios-design-pdf-${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY
diff --git a/docs/leios-design/README.md b/docs/leios-design/README.md
@@ -1,9 +1,9 @@
 ---
-Title: Leios technical design and implementation plan
-Status: Draft
-Version: 0.3
-Authors:
+title: Leios technical design and implementation plan
+author:
   - Sebastian Nagel <[email protected]>
+status: Draft
+version: 0.3
 ---
 
 # Introduction
@@ -121,8 +121,6 @@ Ouroboros Leios is a significant change to the consensus protocol, but does not
 >   - Chain validation: Verifying certificates in blocks
 >   - Staging area interactions?
 >
-> See also this mind map of changes as created by @nfrisby:
-[![](https://mermaid.ink/img/pako:eNqVVdtu2zAM_RVCD0MLJG0uy2XGsGFNt6FAUnRLsIchL6pFx0JsyaPktGnRfx_lwU6yZkX3Ytji5ZCHh_KjiK1CEYlcG5XLYmkAyFp_cjJFbR146dauBbElBIUbd3oaPACCXa2Q6m-AOZKWmX6QXltTHwJMkLwDbeD7BdxapdG9v6UPbZBrPvMWbpCkO3SHUFLszieXl9Paco13UJD1NrYZFJJkjh7JHZgtmzbWa7OCNW5fwqlQNlytOqg2ZJnaWGZzLz1-K5G28IufXPTH2mdRGoTPF5DpXHtXkzGxxqFxpWu32yidfgUxASzRmKmanRSlQto5MMgRIgB-WI_HLHNvSa5wP4GDNug8B2kUM5PtTIt7BzZ5ySOgBKM12fbvWIhlnDZAVT3PyZxhHiayi4MrExOTg-D0w16ZMM9KKiAhm4eC9oexIBkjAW7QePc_U_qkFLMaZ6VCVXXJCrhmyhZ2kmlOBpNUajPfmvjYBFNJan-CN6Qtac9V86sMW5FyI8odMMDz0I77h8yudFybvqJBpx1UtcKMedOsH0_SOB3YYlGj0jEbGy1do7-ztH4JnmSS7DBeLq9J-KZpcZc6cMmbr5vd2lvFGTrHejouwmoNwhwr5Xid48FGNC6FLjBjAN5JhYVPa_MX9HH6D854P2W5Sj2Uxe7ooszW4HhgnKpJQuhSdJ73iPipGGnDatgFofYpUsQtcOe0YX1unpe0VzL3cm5Zb5nDCEIEUttphUBogyQabCaVWTnkkUESzTmll-Fo16n0Jd-eSSZXDhJOz_coFCkvwoGkJ9OrZzJ-9bUmWmJFWonIU4ktkSPlMnyKx5BqKZiGHJci4leFiSwzvxRL88RhhTQ_rc3rSLLMvIgSyRS0RFlwN3ip5Yov3NpFlt6Gzam_OYOIHsW9iEbds-G7bn_YeTvqD_u9cbcltiLqjYZn425v0O8MuqPBaNx9aomHCrJzNh4NOp1Or98b9sadwWDcErwNfI_N_vyUqn8TF4WGyZ_Y0ngRdUdPvwGOCRlc?type=png)](https://mermaid.live/edit#pako:eNqVVdtu2zAM_RVCD0MLJG0uy2XGsGFNt6FAUnRLsIchL6pFx0JsyaPktGnRfx_lwU6yZkX3Ytji5ZCHh_KjiK1CEYlcG5XLYmkAyFp_cjJFbR146dauBbElBIUbd3oaPACCXa2Q6m-AOZKWmX6QXltTHwJMkLwDbeD7BdxapdG9v6UPbZBrPvMWbpCkO3SHUFLszieXl9Paco13UJD1NrYZFJJkjh7JHZgtmzbWa7OCNW5fwqlQNlytOqg2ZJnaWGZzLz1-K5G28IufXPTH2mdRGoTPF5DpXHtXkzGxxqFxpWu32yidfgUxASzRmKmanRSlQto5MMgRIgB-WI_HLHNvSa5wP4GDNug8B2kUM5PtTIt7BzZ5ySOgBKM12fbvWIhlnDZAVT3PyZxhHiayi4MrExOTg-D0w16ZMM9KKiAhm4eC9oexIBkjAW7QePc_U_qkFLMaZ6VCVXXJCrhmyhZ2kmlOBpNUajPfmvjYBFNJan-CN6Qtac9V86sMW5FyI8odMMDz0I77h8yudFybvqJBpx1UtcKMedOsH0_SOB3YYlGj0jEbGy1do7-ztH4JnmSS7DBeLq9J-KZpcZc6cMmbr5vd2lvFGTrHejouwmoNwhwr5Xid48FGNC6FLjBjAN5JhYVPa_MX9HH6D854P2W5Sj2Uxe7ooszW4HhgnKpJQuhSdJ73iPipGGnDatgFofYpUsQtcOe0YX1unpe0VzL3cm5Zb5nDCEIEUttphUBogyQabCaVWTnkkUESzTmll-Fo16n0Jd-eSSZXDhJOz_coFCkvwoGkJ9OrZzJ-9bUmWmJFWonIU4ktkSPlMnyKx5BqKZiGHJci4leFiSwzvxRL88RhhTQ_rc3rSLLMvIgSyRS0RFlwN3ip5Yov3NpFlt6Gzam_OYOIHsW9iEbds-G7bn_YeTvqD_u9cbcltiLqjYZn425v0O8MuqPBaNx9aomHCrJzNh4NOp1Or98b9sadwWDcErwNfI_N_vyUqn8TF4WGyZ_Y0ngRdUdPvwGOCRlc)
 
 > [!CAUTION]
 > FIXME: The next few sections are AI generated based on the impact analysis contents and the (pseudo-)Haskell code should be be replaced by other, similar level of detail specifications (barely scratching the code-level)
@@ -703,7 +701,7 @@ The testnet enables multiple validation categories. Functional testing verifies
 
 The testnet integrates ecosystem tooling: wallets handling increased throughput, block explorers understanding new structures, monitoring systems tracking Leios metrics, and stake pool operator documentation and deployment guides. Crucially, the testnet further enables empirical parameter selection (size limits, timing parameters), where simulation provides initial guidance but real-world testing with community feedback informs acceptable mainnet values.
 
-Software deployed to the public testnet progressively converges toward mainnet release candidates. Early deployments may use instrumented prototypes lacking production optimizations; later upgrades run increasingly complete and optimized implementations. Eventually, all changes as [outlined in this design document](#Architecture) must be realized in the `cardano-node` and other node implementations. This progressive refinement maintains community engagement while preserving engineering velocity. Traces from testnet nodes can still be verified against formal specifications using the trace verification approach, ultimately linking the abstraction layers.
+Software deployed to the public testnet progressively converges toward mainnet release candidates. Early deployments may use instrumented prototypes lacking production optimizations; later upgrades run increasingly complete and optimized implementations. Eventually, all changes as [outlined in this design document](#architecture) must be realized in the `cardano-node` and other node implementations. This progressive refinement maintains community engagement while preserving engineering velocity. Traces from testnet nodes can still be verified against formal specifications using the trace verification approach, ultimately linking the abstraction layers.
 
 ## Mainnet deployment readiness
 

diff --git a/nix/artifacts.nix b/nix/artifacts.nix
@@ -33,7 +33,40 @@ let
     '';
   };
 
+  leiosDesignPdf = pkgs.stdenv.mkDerivation {
+    name = "leios-design-pdf";
+    src = ../docs/leios-design;
+    buildInputs = [
+      pkgs.pandoc
+      pkgs.texliveFull
+      pkgs.librsvg
+      pkgs.typst
+    ];
+    buildPhase = ''
+      # Work directly in the source directory where all assets are available
+      cd $src
+      mkdir -p $out
+
+      # Convert markdown to PDF using pandoc with XeLaTeX
+      pandoc README.md \
+        --pdf-engine=xelatex \
+        --from=markdown \
+        --to=pdf \
+        --output=$out/leios-design.pdf \
+        --table-of-contents \
+        --number-sections \
+        --highlight-style=tango \
+        --variable fontsize=11pt \
+        --variable documentclass=article \
+        --variable geometry:margin=2.5cm \
+        --variable colorlinks=true \
+        --variable linkcolor=blue \
+        --variable urlcolor=blue \
+        --variable toccolor=black
+    '';
+  };
+
 in
 {
-  inherit simRealism networkSpec;
+  inherit simRealism networkSpec leiosDesignPdf;
 }