feat: Arkade Script support (NArk.Arkade package)

.env.regtest

@@ -9,8 +9,8 @@ BITCOIN_LOW_FEE=true
 # signer is S2, with S1 declared deprecated at a far-future cutoff (1900000000 ≈ year 2030). The
 # far-future cutoff keeps S1 inside its collaborative-sweep window, so arkd still co-signs S1 spends
 # (regime 1) and the sweeper can migrate an S1 VTXO onto the current S2 signer.
-ARKD_IMAGE=ghcr.io/arkade-os/arkd:v0.9.12-rc.0
-ARKD_WALLET_IMAGE=ghcr.io/arkade-os/arkd-wallet:v0.9.12-rc.0
+# ARKD_IMAGE=ghcr.io/arkade-os/arkd:v0.9.12-rc.0
+# ARKD_WALLET_IMAGE=ghcr.io/arkade-os/arkd-wallet:v0.9.12-rc.0
 ARKD_WALLET_SIGNER_KEY=9f80812085352f57a5e8104d6406b4d3b191cfdeb96e1321d6284d8d9bb6e8a1
 ARKD_WALLET_DEPRECATED_SIGNER_KEYS=cca401847e4d3635339747f84b7353160acb51951ad287a19f8148835372f1ef:1900000000
 # SDK tests hardcode "ark" for docker exec — keep the override container name consistent.

.github/actions/e2e-setup/action.yml

@@ -1,6 +1,12 @@
 name: E2E Setup
 description: Configure .NET + Node, start regtest infrastructure, build. Requires checkout to have already run.
 
+inputs:
+  profile:
+    description: regtest compose profile(s) to start, comma-separated (e.g. "boltz,delegate" or "solver,boltz").
+    required: false
+    default: boltz,delegate
+
 runs:
   using: composite
   steps:
@@ -12,7 +18,7 @@ runs:
         node-version: '20'
     - name: Start regtest infrastructure
       shell: bash
-      run: node regtest/regtest.mjs start --profile boltz,delegate
+      run: node regtest/regtest.mjs start --profile ${{ inputs.profile }}
     - name: Restore and build
       shell: bash
       run: dotnet build NArk.CI.slnf

.github/workflows/build.yml

@@ -40,10 +40,47 @@ jobs:
     needs: build
     uses: ./.github/workflows/e2e-rotation.yml
 
+  arkade-e2e:
+    name: Arkade E2E Tests (emulator)
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+          fetch-depth: 0
+      # `solver` pulls in `ark` (arkd) + `emulator`, brings up the mock pricefeed + solver, and runs
+      # solver-init (fund + mint asset + register pairs) so the swap fulfill E2E has a live market.
+      # `boltz` adds fulmine (:7003) — the funding endpoint the shared test harness uses to top up
+      # wallets. EMULATOR_SECRET_KEY comes from regtest/.env.defaults (deterministic).
+      - uses: ./.github/actions/e2e-setup
+        with:
+          profile: solver,boltz
+      - name: Run Arkade E2E tests
+        run: dotnet test NArk.Tests.End2End --no-build --verbosity normal --filter "FullyQualifiedName~Arkade"
+        timeout-minutes: 15
+      - name: Collect docker logs on failure
+        if: failure()
+        run: |
+          docker logs arkd > /tmp/arkd-logs.txt 2>&1 || true
+          docker logs emulator > /tmp/emulator-logs.txt 2>&1 || true
+          docker logs solver > /tmp/solver-logs.txt 2>&1 || true
+          docker logs solver-init > /tmp/solver-init-logs.txt 2>&1 || true
+          docker logs bitcoin > /tmp/bitcoin-logs.txt 2>&1 || true
+      - name: Upload logs
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: arkade-docker-logs
+          path: /tmp/*-logs.txt
+      - name: Stop infrastructure
+        if: always()
+        run: node regtest/regtest.mjs clean || true
+
   publish:
     name: Publish NuGet Packages
     runs-on: ubuntu-latest
-    needs: [build, e2e, e2e-swaps, e2e-recovery, e2e-rotation]
+    needs: [build, e2e, e2e-swaps, e2e-recovery, e2e-rotation, arkade-e2e]
     if: github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/')
     permissions:
       contents: write

.github/workflows/e2e-core.yml

@@ -14,9 +14,10 @@ jobs:
           fetch-depth: 0
       - uses: ./.github/actions/e2e-setup
       # Swap and recovery tests run in dedicated parallel workflows (e2e-swaps, e2e-recovery).
-      # Rotation tests run in e2e-rotation. Run everything else here.
+      # Rotation tests run in e2e-rotation. Arkade covenant tests need the emulator profile,
+      # so they run in the arkade-e2e job. Run everything else here.
       - name: Run E2E tests
-        run: dotnet test NArk.Tests.End2End --no-build --verbosity normal --filter "TestCategory!=RealRotation&TestCategory!=Swaps&TestCategory!=Recovery"
+        run: dotnet test NArk.Tests.End2End --no-build --verbosity normal --filter "TestCategory!=RealRotation&TestCategory!=Swaps&TestCategory!=Recovery&FullyQualifiedName!~Arkade"
         timeout-minutes: 20
       - name: Collect docker logs on failure
         if: failure()

NArk.Abstractions/Batches/IBatchSessionExtension.cs

@@ -0,0 +1,66 @@
+using NBitcoin;
+
+namespace NArk.Abstractions.Batches;
+
+/// <summary>
+/// Plug-point invoked by <c>BatchSession</c> at PSBT-emitting points in the
+/// batch flow. Lets extensions co-sign / mutate the PSBTs without
+/// <c>BatchSession</c> needing to know about specific co-signers (emulator,
+/// future custody services, etc.).
+/// </summary>
+/// <remarks>
+/// <para>
+/// Extensions are stateless across batches — they receive the current
+/// spending coins on every call so they can decide per-batch whether to
+/// engage (most often "are any of these coins arkade-bound?").
+/// </para>
+/// <para>
+/// Registered extensions are invoked in DI registration order. An extension
+/// that has nothing to do for a given batch should return the input PSBTs
+/// unchanged from <see cref="CoSignAsync"/> (and <c>false</c> from
+/// <see cref="ShouldHandleAsync"/> if the whole batch is irrelevant — that
+/// short-circuits per-phase calls).
+/// </para>
+/// </remarks>
+public interface IBatchSessionExtension
+{
+    /// <summary>
+    /// Cheap "is this batch relevant to me?" check, called once at batch
+    /// session initialization. <c>BatchSession</c> skips invoking
+    /// <see cref="CoSignAsync"/> on this extension for the rest of the
+    /// batch when this returns <c>false</c>.
+    /// </summary>
+    Task<bool> ShouldHandleAsync(IReadOnlyList<ArkCoin> spendingCoins, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Co-sign / mutate the supplied PSBTs at the given phase of the batch
+    /// flow. The returned list replaces the input (same length, same order);
+    /// extensions can pass through unchanged when there's nothing to do.
+    /// </summary>
+    Task<IReadOnlyList<PSBT>> CoSignAsync(
+        BatchExtensionPhase phase,
+        IReadOnlyList<PSBT> psbts,
+        IReadOnlyList<ArkCoin> spendingCoins,
+        CancellationToken cancellationToken);
+}
+
+/// <summary>
+/// The point in the batch flow at which an <see cref="IBatchSessionExtension"/>
+/// is being invoked.
+/// </summary>
+public enum BatchExtensionPhase
+{
+    /// <summary>
+    /// After tree signing aggregates a partially-signed Ark tx tree, before
+    /// the signatures are submitted upstream. Extension co-signs leaves whose
+    /// inputs need additional signatures (emulator for arkade-bound
+    /// inputs, etc.).
+    /// </summary>
+    PostTreeSigning = 1,
+
+    /// <summary>
+    /// Before forfeit-tx submission and commitment-tx finalisation. Extension
+    /// co-signs forfeits and (optionally) the commitment for inputs it owns.
+    /// </summary>
+    PreForfeitFinalization = 2,
+}

NArk.Abstractions/Helpers/PsbtHelpers.cs

@@ -16,6 +16,8 @@ public static class PsbtHelpers
     private const string VtxoTreeExpiry = "expiry";
     private const string Cosigner = "cosigner";
     private const string ConditionWitness = "condition";
+    private const string PrevArkTx = "prevarktx";
+    private const string PrevoutTx = "prevouttx";
     private const byte ArkPsbtFieldKeyType = 222;
 
     /// <summary>
@@ -57,6 +59,46 @@ public static void SetArkFieldTapTree(this PSBTInput psbtInput, TapScript[] leav
         psbtInput.Unknown[new[] { ArkPsbtFieldKeyType }.Concat(Encoding.UTF8.GetBytes(VtxoTaprootTree)).ToArray()] =
             EncodeTaprootTree(leaves);
 
+    /// <summary>
+    /// Sets the <c>prevarktx</c> ark field — the raw previous Arkade transaction
+    /// an introspection opcode reads for this input. Stored under
+    /// <c>[0xde]||"prevarktx"</c> (emulator <c>ArkFieldPrevArkTx</c>).
+    /// </summary>
+    public static void SetArkFieldPrevArkTx(this PSBTInput psbtInput, Transaction prevArkTx)
+    {
+        ArgumentNullException.ThrowIfNull(prevArkTx);
+        psbtInput.Unknown[new[] { ArkPsbtFieldKeyType }.Concat(Encoding.UTF8.GetBytes(PrevArkTx)).ToArray()] =
+            prevArkTx.ToBytes();
+    }
+
+    /// <summary>
+    /// Sets the <c>prevouttx</c> ark field — the raw previous output transaction
+    /// an introspection opcode reads for this input (e.g. on the emulator's
+    /// <c>/v1/onchain-tx</c> path). Stored under <c>[0xde]||"prevouttx"</c>
+    /// (emulator <c>ArkFieldPrevoutTx</c>).
+    /// </summary>
+    public static void SetArkFieldPrevoutTx(this PSBTInput psbtInput, Transaction prevoutTx)
+    {
+        ArgumentNullException.ThrowIfNull(prevoutTx);
+        psbtInput.Unknown[new[] { ArkPsbtFieldKeyType }.Concat(Encoding.UTF8.GetBytes(PrevoutTx)).ToArray()] =
+            prevoutTx.ToBytes();
+    }
+
+    /// <summary>Reads the <c>prevarktx</c> ark field, or <c>null</c> if absent.</summary>
+    public static Transaction? GetArkFieldPrevArkTx(this PSBTInput psbtInput, Network network) =>
+        GetArkFieldTransaction(psbtInput, PrevArkTx, network);
+
+    /// <summary>Reads the <c>prevouttx</c> ark field, or <c>null</c> if absent.</summary>
+    public static Transaction? GetArkFieldPrevoutTx(this PSBTInput psbtInput, Network network) =>
+        GetArkFieldTransaction(psbtInput, PrevoutTx, network);
+
+    private static Transaction? GetArkFieldTransaction(PSBTInput psbtInput, string fieldName, Network network)
+    {
+        ArgumentNullException.ThrowIfNull(network);
+        var key = new[] { ArkPsbtFieldKeyType }.Concat(Encoding.UTF8.GetBytes(fieldName)).ToArray();
+        return psbtInput.Unknown.TryGetValue(key, out var value) ? Transaction.Load(value, network) : null;
+    }
+
 
     // Encodes taproot script leaves per PSBT spec: {depth version script_length script}* (no leaf count prefix).
     // Param: leaves — array of tapscript byte arrays.