Add experimental unilateral exit (Phase 0) behind an environment gate

.github/dependabot.yml

@@ -8,18 +8,20 @@
 version: 2
 
 updates:
-  # Breez.Sdk.Spark and any other NuGet packages referenced directly by the plugin project.
-  # Pre-1.0 and ships frequent releases, some of them explicit prereleases (e.g. "0.20.0-dev1")
-  # — this repo pins stable only (see the comment on the PackageReference in the .csproj).
-  # No explicit `ignore` rule for that is configured: dependabot.yml's
-  # `ignore.update-types` only supports semver-major/minor/patch, not a "prerelease" type, and
-  # Dependabot's own default behaviour already only proposes stable-to-stable updates when the
-  # pinned version (0.19.2 here) isn't itself a prerelease — confirmed against community reports
-  # of the opposite problem (dependabot/feedback#451: prerelease-pinned projects not being
-  # offered further prereleases), not against a live run of this repo. Watch the first PR
-  # Dependabot opens here to confirm it holds; if it ever proposes a prerelease, an explicit
-  # `ignore: - dependency-name: "Breez.Sdk.Spark", versions: ["*-*"]`-style pattern would be the
-  # fallback (NuGet ignore version patterns are glob-style, not semver ranges).
+  # NuGet packages referenced directly by the plugin project — except Breez.Sdk.Spark, ignored
+  # below: Breez tags and pushes patch versions to NuGet with no GitHub Release and no notes
+  # (0.22.1 through 0.22.3 all shipped that way), and a Dependabot PR per push is churn, not
+  # signal. .github/workflows/breez-sdk-update.yml is the release-aware replacement — proposing a
+  # bump only for versions upstream has published a release for. A tag-only fix worth shipping
+  # early is bumped by hand.
+  #
+  # That split once failed silently in the other direction: the ignore below worked while the pin
+  # was a plain version (no bump proposed between 2026-08-22 and 2026-09-02), and stopped working
+  # as soon as the pin became a bracketed exact-version range (7823e2a changed it on 2026-09-02;
+  # Dependabot proposed a PR for tag-only 0.24.1 on 2026-09-03, PR #65). Two countermeasures
+  # since: `versions: ["*"]` re-routes the ignore through the version-pattern matcher, and
+  # .github/workflows/breez-dependabot-guard.yml closes any Dependabot PR that still names
+  # Breez.Sdk.Spark, so a Dependabot quirk can open nothing but noise that dies without a human.
   #
   # Also note: Dependabot's nuget updater resolves the project's ProjectReference to
   # ../btcpayserver/BTCPayServer/BTCPayServer.csproj, which lives in a git submodule; this is
@@ -32,6 +34,12 @@ updates:
     open-pull-requests-limit: 5
     commit-message:
       prefix: "chore(deps)"
+    ignore:
+      # The versions condition is not a statement that some versions may be proposed: it matches
+      # every version, on the strength of the incident described above — make the ignore survive
+      # whatever format the PackageReference pin takes next.
+      - dependency-name: "Breez.Sdk.Spark"
+        versions: ["*"]
 
   # Test-project NuGet packages -- xunit.v3, and since the move to Microsoft.Testing.Platform that is the
   # whole list; the VSTest host and adapter it used to name here are gone. Separate entry because

.github/release-notes-template.md

@@ -30,10 +30,8 @@ writes it with a single space between hash and filename. GNU `sha256sum -c` acce
 
 ## Installing
 
-**Server settings → Plugins → Upload plugin**, and select `BTCPayServer.Plugins.Flint.btcpay`.
-BTCPay restarts itself to finish. Requires BTCPay Server 2.4.1 or newer, on a non-Alpine host.
+**Server settings → Plugins**, find **Flint** in the plugin store ([official listing](https://plugin-builder.btcpayserver.org/public/plugins/flint)), and install it. BTCPay restarts itself to finish.
 
-Read [CHANGELOG.md](https://github.com/__REPO__/blob/__TAG__/CHANGELOG.md) for what is in this
-release and how far it has actually been proven, and the
-[trust model](https://github.com/__REPO__/blob/__TAG__/docs/trust-model.md), before you put money
-through it.
+Alternatively, **Server settings → Plugins → Upload plugin**, and select `BTCPayServer.Plugins.Flint.btcpay`. BTCPay restarts itself to finish. Both routes require BTCPay Server 2.4.1 or newer, on a non-Alpine host.
+
+Read the [CHANGELOG](https://github.com/__REPO__/blob/__TAG__/CHANGELOG.md) for what is in this release and how far it has actually been proven, and the [trust model](https://github.com/__REPO__/blob/__TAG__/docs/trust-model.md), before you put money through it.

.github/workflows/breez-dependabot-guard.yml

@@ -0,0 +1,55 @@
+name: Breez Dependabot guard
+
+# Dependabot's NuGet ignore rules are not a reliable gate: the name-only ignore for
+# Breez.Sdk.Spark held while the pin was a plain version, and silently stopped working the day
+# the pin became a bracketed exact range (7823e2a, 2026-09-02) — Dependabot proposed a PR for
+# tag-only 0.24.1 the next morning (PR #65, 2026-09-03), defeating the policy that Breez bumps
+# arrive only from .github/workflows/breez-sdk-update.yml, which proposes a version only when
+# upstream has a *published GitHub Release* for it (see the comment on that workflow and on
+# dependabot.yml for why tag-only bumps are deliberate churn).
+#
+# This workflow enforces that policy at the PR layer instead of trusting the ignore: any PR
+# authored by Dependabot that names Breez.Sdk.Spark is closed and its branch deleted. Human
+# PRs (including hand-applied tag-only bumps) are untouched: the guard fires only for
+# dependabot[bot]. If a Dependabot quirk resurrects a PR, this closes it without a human ever
+# having to look at it.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  guard:
+    name: Close Dependabot Breez.Sdk.Spark PR
+    # Fails closed: a PR not authored by dependabot[bot], or already deleted before this job
+    # runs, is a no-op, not an error.
+    if: >-
+      github.actor == 'dependabot[bot]' &&
+      contains(github.event.pull_request.title, 'Breez.Sdk.Spark')
+    runs-on: ubuntu-latest
+    permissions:
+      # Deleting the guarded PR's branch needs contents; closing + commenting needs PRs.
+      contents: write
+      pull-requests: write
+    steps:
+      # No checkout needed: gh acts on the PR number directly.
+      - name: Close the PR and delete its branch
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          comment="$(cat <<BODY
+          Closed automatically by \`.github/workflows/breez-dependabot-guard.yml\`.
+
+          Dependabot's ignore for \`Breez.Sdk.Spark\` has a documented hole when the PackageReference
+          pin changes format (name-only ignore defeated by an exact-version bracket), so Breez bump
+          PRs must arrive only from \`.github/workflows/breez-sdk-update.yml\`, which proposes a
+          version only when upstream has a published GitHub Release for it. A tag-only fix worth
+          shipping early is bumped by hand.
+          BODY
+          )"
+          gh pr close "$PR" --comment "$comment" --delete-branch --repo "$GITHUB_REPOSITORY"

.github/workflows/breez-sdk-update.yml

@@ -0,0 +1,156 @@
+name: Breez SDK update
+
+# Dependabot's nuget ecosystem proposes a PR for every Breez.Sdk.Spark version pushed to NuGet,
+# and Breez tags and pushes patch versions with no GitHub Release and no notes (0.22.1 through
+# 0.22.3 all shipped that way) — a PR per push is churn, not signal. This workflow is the
+# release-aware equivalent, mirroring btcpayserver-update.yml for the same reason that one
+# replaced Dependabot's gitsubmodule ecosystem: weekly plus on-demand, it looks for the newest
+# version breez/spark-sdk has a *published GitHub Release* for (that also exists on NuGet, so
+# the PR can restore), and opens a bump PR only then. Breez.Sdk.Spark is ignored in
+# dependabot.yml so the two do not both propose bumps; because that ignore proved leaky once the
+# pin format changed (see breez-dependabot-guard.yml), a guard workflow also closes any
+# Dependabot PR that names Breez.Sdk.Spark — the release gate is enforced, not assumed.
+# A tag-only fix worth shipping early is a
+# human decision: bump the PackageReference by hand, exactly as 0.22.2 and 0.22.3 were.
+#
+# Token: default GITHUB_TOKEN, with the same workflow_dispatch re-dispatch trick as
+# btcpayserver-update.yml so ci.yml actually runs on the PR this opens (GITHUB_TOKEN-authored
+# pushes do not fire pull_request workflows; workflow_dispatch is exempt from that rule).
+
+on:
+  schedule:
+    - cron: "0 6 * * 2"  # Tuesdays 06:00 UTC — offset from the Monday btcpayserver check
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Detect only: print the result and diff, but do not push or open a PR"
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+  pull-requests: write
+  actions: write  # to re-dispatch ci.yml on the bump branch, see above
+
+jobs:
+  check:
+    name: Check for a newer Breez SDK release
+    runs-on: ubuntu-latest
+    # Discovery only reads the csproj and talks to the NuGet/GitHub APIs: the
+    # write powers the bump job needs must not leak into the scheduled check.
+    permissions:
+      contents: read
+    outputs:
+      changed: ${{ steps.check.outputs.changed }}
+      current: ${{ steps.check.outputs.current }}
+      latest: ${{ steps.check.outputs.latest }}
+      release_url: ${{ steps.check.outputs.release_url }}
+    steps:
+      # No submodule checkout needed: the discovery script only reads the csproj and queries the
+      # GitHub and NuGet APIs, so this stays cheap enough to run unconditionally every week.
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Run discovery script
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          out="$(scripts/check-breez-sdk-update.sh)"
+          echo "Discovery result: $out"
+          {
+            echo "changed=$(jq -r .changed <<<"$out")"
+            echo "current=$(jq -r .current <<<"$out")"
+            echo "latest=$(jq -r .latest <<<"$out")"
+            echo "release_url=$(jq -r .release_url <<<"$out")"
+          } >> "$GITHUB_OUTPUT"
+
+  bump:
+    name: Open bump PR
+    needs: check
+    if: ${{ needs.check.outputs.changed == 'true' }}
+    runs-on: ubuntu-latest
+    env:
+      CURRENT: ${{ needs.check.outputs.current }}
+      LATEST: ${{ needs.check.outputs.latest }}
+      RELEASE_URL: ${{ needs.check.outputs.release_url }}
+      DRY_RUN: ${{ github.event.inputs.dry_run }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump Breez.Sdk.Spark to ${{ needs.check.outputs.latest }}
+        run: |
+          set -euo pipefail
+          # The pin is an exact-version bracket pin (Version="[0.25.0]"): the sed keeps the
+          # brackets on the way out, and \[?[0-9][0-9.]*\]? also survives a future unbracketed
+          # pin. The guard greps fixed-string, since a literal "[0.24.0]" would otherwise be a
+          # character class to grep.
+          sed -i -E \
+            "s|(<PackageReference Include=\"Breez.Sdk.Spark\" Version=\")\[?[0-9][0-9.]*\]?(\")|\1[$LATEST]\2|" \
+            BTCPayServer.Plugins.Flint/BTCPayServer.Plugins.Flint.csproj
+          if ! grep -qF "Include=\"Breez.Sdk.Spark\" Version=\"[$LATEST]\"" \
+            BTCPayServer.Plugins.Flint/BTCPayServer.Plugins.Flint.csproj; then
+            echo "error: the PackageReference did not end up at [$LATEST]; refusing to open a PR" >&2
+            exit 1
+          fi
+          git add BTCPayServer.Plugins.Flint/BTCPayServer.Plugins.Flint.csproj
+          git status --short
+
+      - name: Create branch and commit
+        id: commit
+        run: |
+          set -euo pipefail
+          branch="chore/breez-sdk-$LATEST"
+          echo "branch=$branch" >> "$GITHUB_OUTPUT"
+
+          if [ "$DRY_RUN" = "true" ]; then
+            echo "DRY RUN — diff only, not pushing:"
+            git --no-pager diff --cached
+            exit 0
+          fi
+
+          git switch -c "$branch"
+          git commit -m "Bump Breez.Sdk.Spark to $LATEST"
+          git push -f origin "$branch"
+
+      - name: Open or update PR
+        if: ${{ github.event.inputs.dry_run != 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BRANCH: ${{ steps.commit.outputs.branch }}
+        run: |
+          set -euo pipefail
+          title="Bump Breez.Sdk.Spark: $CURRENT -> $LATEST"
+          body="$(cat <<BODY
+          Bumps \`Breez.Sdk.Spark\` from \`$CURRENT\` to \`$LATEST\`, a version upstream has published
+          a GitHub Release for — tag-only NuGet pushes are deliberately not proposed (see
+          \`.github/workflows/breez-sdk-update.yml\`).
+
+          Upstream release notes: $RELEASE_URL
+
+          The SDK is pre-1.0 with no stability promise between releases: read the notes (when they
+          exist) and the API-surface diff before merging, per the pinning comment on the
+          PackageReference. CI on this PR — including the live and funded regtest suites — is the
+          merge gate, not a substitute for that read.
+          BODY
+          )"
+
+          open_count="$(gh pr list --head "$BRANCH" --state open --json number --jq 'length')"
+          if [ "$open_count" = "0" ]; then
+            gh pr create --base main --head "$BRANCH" --title "$title" --body "$body"
+            echo "Opened PR for $BRANCH."
+          else
+            gh pr edit "$BRANCH" --title "$title" --body "$body"
+            echo "PR already open for $BRANCH; force-pushed branch updated it."
+          fi
+
+          # See the workflow-level comment: workflow_dispatch is exempt from GITHUB_TOKEN's
+          # loop-prevention rule, so this is what actually gets ci.yml to run on the PR.
+          gh workflow run ci.yml --ref "$BRANCH"

.github/workflows/btcpayserver-update.yml

@@ -37,6 +37,10 @@ jobs:
   check:
     name: Check for a newer stable btcpayserver release
     runs-on: ubuntu-latest
+    # Discovery only reads Constants.cs and runs git ls-remote: the write
+    # powers the bump job needs must not leak into the scheduled check.
+    permissions:
+      contents: read
     outputs:
       changed: ${{ steps.check.outputs.changed }}
       current: ${{ steps.check.outputs.current }}
@@ -47,7 +51,7 @@ jobs:
       # repo and queries the upstream remote's tag list over the network (git ls-remote), so this
       # stays cheap enough to run unconditionally every week.
       - name: Check out repository
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Run discovery script
         id: check
@@ -74,10 +78,20 @@ jobs:
       DRY_RUN: ${{ github.event.inputs.dry_run }}
     steps:
       - name: Check out repository
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 
+      # Lock regeneration needs the .NET SDK: the submodule bump changes the ProjectReference
+      # version constraints (btcpayserver's Build/Version.csproj carries the release number), and
+      # the committed packages.lock.json files must be regenerated to match. Without this step the
+      # bump PR fails CI at "Restore (locked mode)" with NU1004, as seen on chore/btcpayserver-v2.4.3
+      # (run 184, 2026-09-07) — the bump step edited the submodule but never the locks.
+      - name: Set up .NET
+        uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
+        with:
+          dotnet-version: "10.0.x"
+
       - name: Configure git identity
         run: |
           git config user.name "github-actions[bot]"
@@ -101,7 +115,19 @@ jobs:
             BTCPayServer.Plugins.Flint/Constants.cs
           sed -i -E "s/\`v[0-9]+\.[0-9]+\.[0-9]+\`\)\./\`v$LATEST\`)./" docs/building.md
 
-          git add btcpayserver BTCPayServer.Plugins.Flint/Constants.cs docs/building.md
+          # Regenerate the committed lock files against the bumped graph, then prove they agree
+          # with it under locked mode — the same property CI's "Restore (locked mode)" checks on
+          # the PR, so a lock that drifts from the csprojs fails here at the bump step, before a
+          # PR anyone has to review even exists. Unlocked restore rewrites them in place; locked
+          # re-restore must then be a no-op.
+          dotnet restore BTCPayServer.Plugins.Flint/BTCPayServer.Plugins.Flint.csproj
+          dotnet restore BTCPayServer.Plugins.Flint.Tests/BTCPayServer.Plugins.Flint.Tests.csproj
+          dotnet restore --locked-mode BTCPayServer.Plugins.Flint/BTCPayServer.Plugins.Flint.csproj
+          dotnet restore --locked-mode BTCPayServer.Plugins.Flint.Tests/BTCPayServer.Plugins.Flint.Tests.csproj
+
+          git add btcpayserver BTCPayServer.Plugins.Flint/Constants.cs docs/building.md \
+            BTCPayServer.Plugins.Flint/packages.lock.json \
+            BTCPayServer.Plugins.Flint.Tests/packages.lock.json
           git status --short
 
       - name: Create branch and commit