docs: privacy-preserving SPEL programs guide

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## Description
+<!-- What does this PR do? Why? -->
+
+## Changes
+<!-- List key changes -->
+
+## Checklist
+- [ ] Builds cleanly (`make build` or `cmake --build`)
+- [ ] Tests pass (`make test` or `ctest -V`)
+- [ ] README updated if new features, CLI commands, or behaviour changed
+- [ ] New public methods have doc comments
+- [ ] Branch is off `main` (not another feature branch)

.github/workflows/ci.yml

@@ -5,15 +5,116 @@ on:
   push:
     branches: [main]
 
+env:
+  CARGO_TERM_COLOR: always
+
 jobs:
-  test:
-    name: Tests
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          prefix-key: "unit"
+      - name: Build (framework + codegen)
+        run: cargo build -p spel-framework -p spel-framework-core -p spel-framework-macros -p spel-client-gen
+      - name: Unit tests
+        run: cargo test -p spel-framework-core -p spel-framework-macros -p spel-client-gen
+
+  e2e-tests:
+    name: E2E Tests
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
-      - name: Build (core + macros)
-        run: cargo build -p nssa-framework -p nssa-framework-core -p nssa-framework-macros
-      - name: Test (core + macros)
-        run: cargo test -p nssa-framework -p nssa-framework-core -p nssa-framework-macros
+        with:
+          prefix-key: "e2e"
+      - name: Install logos-blockchain-circuits
+        run: |
+          curl -sSL https://raw.githubusercontent.com/logos-blockchain/logos-blockchain/main/scripts/setup-logos-blockchain-circuits.sh | bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build (all packages including spel)
+        run: cargo build -p spel-framework -p spel-framework-core -p spel-framework-macros -p spel-client-gen -p spel
+      - name: E2E tests
+        run: cargo test -p spel-framework
+
+  privacy-smoke-test:
+    name: Privacy Smoke Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      RISC0_VERSION: "3.0.5"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          prefix-key: "privacy"
+
+      - name: Generate Cargo.lock
+        run: cargo generate-lockfile
+      - name: Extract LEZ commit from spel-framework/Cargo.toml
+        id: lez-ref
+        run: |
+          LEZ_REV=$(grep 'nssa_core' spel-framework/Cargo.toml | grep -o 'rev = "[^"]*"' | cut -d'"' -f2)
+          echo "LEZ_REV=$LEZ_REV" >> $GITHUB_OUTPUT
+          echo "Using LEZ commit: $LEZ_REV"
+
+      - name: Install risc0 toolchain
+        run: |
+          curl -L https://risczero.com/install | bash
+          echo "$HOME/.risc0/bin" >> $GITHUB_PATH
+          export PATH="$HOME/.risc0/bin:$PATH"
+          rzup install cargo-risczero ${{ env.RISC0_VERSION }}
+          rzup install rust
+
+      - name: Install logos-blockchain-circuits
+        run: |
+          curl -sSL https://raw.githubusercontent.com/logos-blockchain/logos-blockchain/main/scripts/setup-logos-blockchain-circuits.sh | bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install spel
+        run: cargo install --path spel-cli --locked
+
+      - name: Clone LEZ at correct commit
+        run: |
+          git clone --depth 1 https://github.com/logos-blockchain/logos-execution-zone.git /tmp/lssa || true
+          cd /tmp/lssa
+          git fetch --depth 1 origin ${{ steps.lez-ref.outputs.LEZ_REV }}
+          git checkout ${{ steps.lez-ref.outputs.LEZ_REV }}
+
+      - name: Cache sequencer
+        id: cache-seq
+        uses: actions/cache@v4
+        with:
+          path: /tmp/lssa/target/release/sequencer_service
+          key: sequencer-${{ steps.lez-ref.outputs.LEZ_REV }}
+
+      - name: Build sequencer
+        if: steps.cache-seq.outputs.cache-hit != 'true'
+        run: |
+          cd /tmp/lssa
+          cargo build --release --features standalone -p sequencer_service
+
+      - name: Build wallet
+        run: |
+          cd /tmp/lssa
+          cargo build --release -p wallet
+
+      - name: Setup wallet
+        run: |
+          mkdir -p /tmp/wallet
+          echo '{"sequencer_addr":"http://127.0.0.1:3040","seq_poll_timeout":"30s","seq_tx_poll_max_blocks":15,"seq_poll_max_retries":10,"seq_block_poll_max_amount":100,"initial_accounts":[{"Public":{"account_id":"CbgR6tj5kWx5oziiFptM7jMvrQeYY3Mzaao6ciuhSr2r","pub_sign_key":"7f273098f25b71e6c005a9519f2678da8d1c7f01f6a27778e2d9948abdf901fb"}},{"Public":{"account_id":"2RHZhw9h534Zr3eq2RGhQete2Hh667foECzXPmSkGni2","pub_sign_key":"f434f8741720014586ae43356d2aec6257da086222f604ddb75d69733b86fc4c"}}]}' > /tmp/wallet/wallet_config.json
+
+      - name: Run privacy smoke test
+        env:
+          NSSA_WALLET_HOME_DIR: /tmp/wallet
+          LSSA_DIR: /tmp/lssa
+        run: |
+          export PATH="/tmp/lssa/target/release:$PATH"
+          scripts/smoke-test-privacy.sh /tmp/privacy-smoke

.github/workflows/lez-compat.yml

@@ -0,0 +1,104 @@
+name: LEZ Compatibility Check
+
+on:
+  schedule:
+    # Every Monday at 06:00 UTC
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+    inputs:
+      lez_ref:
+        description: 'LEZ commit/branch to test against (default: main)'
+        required: false
+        default: 'main'
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  lez-compat:
+    name: Check SPEL against latest LEZ
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          prefix-key: "lez-compat"
+
+      - name: Get latest LEZ commit
+        id: lez
+        run: |
+          REF="${{ github.event.inputs.lez_ref || 'main' }}"
+          COMMIT=$(git ls-remote https://github.com/logos-blockchain/logos-execution-zone.git "$REF" | head -1 | cut -f1)
+          echo "commit=$COMMIT" >> "$GITHUB_OUTPUT"
+          echo "ref=$REF" >> "$GITHUB_OUTPUT"
+          echo "🔍 Testing against LEZ $REF ($COMMIT)"
+
+      - name: Update LEZ deps to latest
+        run: |
+          COMMIT="${{ steps.lez.outputs.commit }}"
+          echo "Updating all LEZ deps to $COMMIT"
+
+          # Find all Cargo.toml files with LEZ git deps
+          find . -name Cargo.toml -exec grep -l 'logos-execution-zone\|logos-blockchain/lssa' {} \; | while read f; do
+            # Update rev= pins
+            sed -i "s|rev = \"[a-f0-9]\{40\}\"|rev = \"$COMMIT\"|g" "$f"
+            # Ensure URL points to new repo name
+            sed -i "s|logos-blockchain/lssa\.git|logos-blockchain/logos-execution-zone.git|g" "$f"
+            echo "  Updated: $f"
+          done
+
+      - name: cargo check (spel-cli)
+        run: cargo check -p spel-cli
+
+      - name: cargo check (spel-framework)
+        run: cargo check -p spel-framework
+
+      - name: cargo check (spel-framework-core)
+        run: cargo check -p spel-framework-core
+
+      - name: Report
+        if: always()
+        run: |
+          echo "## LEZ Compatibility Report" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **LEZ ref:** ${{ steps.lez.outputs.ref }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **LEZ commit:** \`${{ steps.lez.outputs.commit }}\`" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **SPEL ref:** \`$(git rev-parse HEAD)\`" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Create issue on failure
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const commit = '${{ steps.lez.outputs.commit }}';
+            const ref = '${{ steps.lez.outputs.ref }}';
+            const title = `LEZ compatibility broken (${ref}: ${commit.slice(0, 8)})`;
+
+            // Check for existing open issue
+            const existing = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: 'lez-compat',
+              per_page: 1,
+            });
+
+            if (existing.data.length > 0) {
+              // Comment on existing issue
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.data[0].number,
+                body: `Still broken as of LEZ \`${commit}\` (${ref}).\n\nRun: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+              });
+            } else {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title,
+                labels: ['lez-compat'],
+                body: `The weekly LEZ compatibility check failed.\n\n- **LEZ ref:** ${ref}\n- **LEZ commit:** \`${commit}\`\n- **Run:** ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}\n\nPlease update SPEL to match the latest LEZ API changes.`,
+              });
+            }

.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish Release
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+jobs:
+  publish-release:
+    name: Publish Release
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.merged == true && startsWith(github.head_ref, 'release/v')
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from branch
+        id: version
+        run: |
+          VERSION=${GITHUB_HEAD_REF#release/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Extracted version: $VERSION"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.version }}
+          name: v${{ steps.version.outputs.version }}
+          body: |
+            ## v${{ steps.version.outputs.version }}
+
+            See [CHANGELOG.md](https://github.com/logos-co/spel/blob/main/CHANGELOG.md) for full details.
+
+            ---
+
+            **Installation** (Cargo.toml):
+            ```toml
+            spel-framework = { git = "https://github.com/logos-co/spel.git", tag = "v${{ steps.version.outputs.version }}" }
+            ```
+          draft: false
+          prerelease: false