feat(contracts): per-type ContractScope (on-chain/off-chain) as a first-class property

Replaces the scattered `Type == "Boarding"` checks that implicitly decided
whether a contract's funds live on-chain (boarding UTXOs) or off-chain (VTXOs).

- New `[Flags] ContractScope { Onchain = 1, Offchain = 2 }` (Both = Onchain|Offchain).
- `ArkContract.DefaultScope` (abstract — every type must declare its scope, so a
  new type can't silently inherit a wrong default): Boarding => Onchain; Payment,
  HashLockPayment, Delegate, VHTLC, Note, Unknown, Generic => Offchain.
- Resolved scope persisted on `ArkContractEntity.Scope` / `ArkWalletContractEntity`
  (indexed). `ToEntity(scopeOverride:)` is the per-instance escape hatch
  (Scope = scopeOverride ?? DefaultScope); nothing sets it yet.
- `IContractStorage.GetContracts(scope:)` filters via the SQL-translatable bitwise
  predicate `(Scope & s) == s` (NOT HasFlag, which EF can't translate).
- Consumers migrated off the boarding-type check: BoardingUtxoPollService,
  BoardingUtxoSyncService, OnchainSweepService -> scope: Onchain;
  WalletRecoveryService -> offchain bitwise filter.

Tests (TDD): per-type DefaultScope, ToEntity override resolution, flags semantics,
and a SQLite-backed GetContracts(scope:) test (real SQLite, not InMemory — InMemory
client-evaluates and would hide a non-translatable query).

Schema note: NArk.Storage.EfCore is provider-agnostic with no migrations history —
the Scope column ships via entity configuration. Consumers that manage their own
schema with EF migrations should add a migration creating the column (default
Offchain) and backfilling existing boarding rows to Onchain.

Author: Kukks

NArk.Abstractions/Contracts/ArkContract.cs

@@ -11,6 +11,13 @@ public abstract class ArkContract(OutputDescriptor server)
 
     public abstract string Type { get; }
 
+    /// <summary>
+    /// The layer this contract type's funds live on by default (on-chain vs off-chain).
+    /// Abstract so every contract type makes an explicit, compile-time scope decision.
+    /// Used as the fallback when <see cref="ToEntity"/> is called without a scope override.
+    /// </summary>
+    public abstract ContractScope DefaultScope { get; }
+
     public OutputDescriptor? Server { get; } = server;
 
     public virtual ArkAddress GetArkAddress(OutputDescriptor? defaultServerKey = null)
@@ -53,11 +60,24 @@ public virtual Script GetScriptPubKey()
         return spendInfo.OutputPubKey.ScriptPubKey;
     }
 
+    /// <summary>
+    /// Projects this contract into a persistable <see cref="ArkContractEntity"/>.
+    /// </summary>
+    /// <param name="walletIdentifier">The wallet that owns the contract.</param>
+    /// <param name="defaultServerKey">Reserved for address derivation parity; not persisted.</param>
+    /// <param name="createdAt">Creation timestamp; defaults to now.</param>
+    /// <param name="activityState">Initial activity state; defaults to Active.</param>
+    /// <param name="scopeOverride">
+    /// Per-instance scope override. When null, the entity's effective scope is
+    /// <see cref="DefaultScope"/>. The override is write-time only — the persisted
+    /// column always means "this contract's effective scope."
+    /// </param>
     public ArkContractEntity ToEntity(
         string walletIdentifier,
         OutputDescriptor? defaultServerKey = null,
         DateTimeOffset? createdAt = null,
-        ContractActivityState activityState = ContractActivityState.Active)
+        ContractActivityState activityState = ContractActivityState.Active,
+        ContractScope? scopeOverride = null)
     {
         return new ArkContractEntity(
             GetScriptPubKey().ToHex(),
@@ -66,7 +86,10 @@ public ArkContractEntity ToEntity(
             GetContractData(),
             walletIdentifier,
             createdAt ?? DateTimeOffset.UtcNow
-        );
+        )
+        {
+            Scope = scopeOverride ?? DefaultScope
+        };
     }
 
     protected abstract IEnumerable<ScriptBuilder> GetScriptBuilders();

NArk.Abstractions/Contracts/ArkContractEntity.cs

@@ -14,4 +14,10 @@ DateTimeOffset CreatedAt
     /// Separate from AdditionalData which stores contract crypto params.
     /// </summary>
     public Dictionary<string, string>? Metadata { get; init; }
+
+    /// <summary>
+    /// The effective layer this contract's funds live on (on-chain vs off-chain).
+    /// Resolved at write time from the contract's <c>DefaultScope</c> or an explicit override.
+    /// </summary>
+    public ContractScope Scope { get; init; }
 }

NArk.Abstractions/Contracts/ContractScope.cs

@@ -0,0 +1,24 @@
+namespace NArk.Abstractions.Contracts;
+
+/// <summary>
+/// Identifies the layer a contract's funds live on: on-chain (a boarding UTXO,
+/// synced/swept via Esplora/NBXplorer) or off-chain (a VTXO, synced via the
+/// Arkade indexer). A contract whose funds can appear on both layers uses
+/// <see cref="Onchain"/> | <see cref="Offchain"/>.
+/// </summary>
+/// <remarks>
+/// Query this only via the bitwise form <c>(Scope &amp; X) == X</c>, which EF Core
+/// translates to SQL across Npgsql, SQLite and SqlServer. A value carrying both
+/// flags therefore satisfies an <see cref="Onchain"/>-include and an
+/// <see cref="Offchain"/>-include filter alike. Never use <c>HasFlag</c>: EF Core
+/// does not translate it (it client-evaluates or throws).
+/// </remarks>
+[Flags]
+public enum ContractScope
+{
+    /// <summary>Funds live on-chain (a boarding UTXO).</summary>
+    Onchain = 1,
+
+    /// <summary>Funds live off-chain (a VTXO synced via the Arkade indexer).</summary>
+    Offchain = 2,
+}

NArk.Abstractions/Contracts/IContractStorage.cs

@@ -17,6 +17,10 @@ public interface IContractStorage : IActiveScriptsProvider
     /// <param name="searchText">Filter by script containing this text. If null, no text filter.</param>
     /// <param name="skip">Number of records to skip (for pagination). If null, no skip.</param>
     /// <param name="take">Number of records to take (for pagination). If null, no limit.</param>
+    /// <param name="scope">
+    /// Filter by contract scope (on-chain/off-chain) via bitwise include
+    /// <c>(Scope &amp; scope) == scope</c>. If null, no scope filter.
+    /// </param>
     /// <param name="cancellationToken">Cancellation token.</param>
     Task<IReadOnlyCollection<ArkContractEntity>> GetContracts(
         string[]? walletIds = null,
@@ -26,6 +30,7 @@ Task<IReadOnlyCollection<ArkContractEntity>> GetContracts(
         string? searchText = null,
         int? skip = null,
         int? take = null,
+        ContractScope? scope = null,
         CancellationToken cancellationToken = default);
 
     Task SaveContract(ArkContractEntity walletEntity, CancellationToken cancellationToken = default);

NArk.Core/Contracts/ArkBoardingContract.cs

@@ -22,6 +22,9 @@ public class ArkBoardingContract(OutputDescriptor server, Sequence exitDelay, Ou
     public override string Type => ContractType;
     public const string ContractType = "Boarding";
 
+    /// <summary>Boarding funds live on-chain as a boarding UTXO.</summary>
+    public override ContractScope DefaultScope => ContractScope.Onchain;
+
 
     /// <summary>
     /// Boarding contracts use on-chain Bitcoin addresses, not Ark addresses.

NArk.Core/Contracts/ArkDelegateContract.cs

@@ -18,6 +18,9 @@ public class ArkDelegateContract : ArkContract
     public override string Type => ContractType;
     public const string ContractType = "Delegate";
 
+    /// <summary>Delegate funds live off-chain as a VTXO.</summary>
+    public override ContractScope DefaultScope => ContractScope.Offchain;
+
     public ArkDelegateContract(
         OutputDescriptor server,
         Sequence exitDelay,

NArk.Core/Contracts/ArkNoteContract.cs

@@ -19,6 +19,9 @@ public class ArkNoteContract(uint amount, byte[] preimage) : ArkContract(null!)
     public override string Type => ContractType;
     public const string ContractType = "arknote";
 
+    /// <summary>Arkade note funds live off-chain as a VTXO.</summary>
+    public override ContractScope DefaultScope => ContractScope.Offchain;
+
     protected override IEnumerable<ScriptBuilder> GetScriptBuilders()
     {
         yield return CreateClaimScript();

NArk.Core/Contracts/ArkPaymentContract.cs

@@ -21,6 +21,9 @@ public class ArkPaymentContract(OutputDescriptor server, Sequence exitDelay, Out
     public override string Type => ContractType;
     public const string ContractType = "Payment";
 
+    /// <summary>Payment funds live off-chain as a VTXO.</summary>
+    public override ContractScope DefaultScope => ContractScope.Offchain;
+
 
     protected override IEnumerable<ScriptBuilder> GetScriptBuilders()
     {

NArk.Core/Contracts/GenericArkContract.cs

@@ -8,6 +8,9 @@ public class GenericArkContract(OutputDescriptor server, IEnumerable<ScriptBuild
 {
     public override string Type { get; } = "generic";
 
+    /// <summary>Generic contracts default to off-chain (VTXO) unless overridden at write time.</summary>
+    public override ContractScope DefaultScope => ContractScope.Offchain;
+
     protected override IEnumerable<ScriptBuilder> GetScriptBuilders()
     {
         return scriptBuilders;

NArk.Core/Contracts/HashLockedArkPaymentContract.cs

@@ -40,6 +40,9 @@ public byte[] Hash
 
     public override string Type => ContractType;
     public const string ContractType = "HashLockPaymentContract";
+
+    /// <summary>Hash-locked payment funds live off-chain as a VTXO.</summary>
+    public override ContractScope DefaultScope => ContractScope.Offchain;
     public byte[] Preimage => preimage;
     public Sequence ExitDelay => _exitDelay;
     public HashLockTypeOption HashLockType => hashLockType;