Skip to content

Commit a05f1fb

Browse files
committed
refactor(swaps): rename preimage tag NArk → Arkade for cross-SDK interop
NArk is the .NET SDK's internal shorthand; using it in the on-the-wire derivation tag locks the scheme to one specific SDK implementation. The preimage is rooted in BIP-340 signing of a fixed message — there's nothing about it that's .NET-specific. Renaming the tag to "Arkade- Boltz-Preimage-v1" lets any Arkade SDK (ts-sdk, go-sdk, rust-sdk, NArk) implement the same scheme byte-for-byte and recover swaps that another SDK created, which is the entire point of having a documented spec for the message construction. Arkade is the protocol brand per CLAUDE.md; Boltz is the provider (future Loop/Submarine/etc. would have their own tag); -v1 stays as the version hook. Pre-merge: nothing has shipped under the old tag yet, so this is a free rename — no v1/v2 fallback needed. docs/articles/swaps.md updated to make the cross-SDK interop intent explicit so any future implementer knows the tag is canonical and not an SDK-specific opaque value.
1 parent d643a3b commit a05f1fb

2 files changed

Lines changed: 6 additions & 3 deletions

File tree

NArk.Swaps/Services/SwapsManagementService.cs

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,10 @@ public ISwapProvider ResolveProvider(SwapRoute route, string? preferredProviderI
119119
// Local signing sources pass aux_rand=null to BIP-340, so signatures are deterministic.
120120
// Remote-signer transports MUST honour the same convention or the preimage will rotate
121121
// per call and recovery will silently fail — see IRemoteSignerTransport.SignAsync.
122-
private const string PreimageTag = "NArk-Boltz-Preimage-v1";
122+
// Tag is protocol+provider scoped (Arkade brand, Boltz provider), not SDK-scoped, so any
123+
// Arkade SDK implementing the same scheme produces the same preimage and can recover
124+
// swaps the .NET SDK created (and vice versa). Versioned ("-v1") for future scheme evolution.
125+
private const string PreimageTag = "Arkade-Boltz-Preimage-v1";
123126
private static readonly byte[] PreimageTagBytes = Encoding.UTF8.GetBytes(PreimageTag);
124127

125128
private async Task<byte[]> DerivePreimageAsync(

docs/articles/swaps.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -110,14 +110,14 @@ Typical states recorded against each `ArkSwap`:
110110
The preimages we generate for reverse and chain swaps are derived deterministically from the wallet's signing material so that a restored wallet can re-derive them and claim outstanding VHTLCs. The scheme:
111111

112112
```
113-
message = SHA-256( "NArk-Boltz-Preimage-v1" || descriptor.ToString() || u32_le(index) )
113+
message = SHA-256( "Arkade-Boltz-Preimage-v1" || descriptor.ToString() || u32_le(index) )
114114
sig = BIP-340-Schnorr( descriptor_key, message, aux_rand=null )
115115
preimage = SHA-256( sig )
116116
```
117117

118118
The signed input bundles three things:
119119

120-
- **Tag** — domain-separates this signature from any other use of the descriptor's key. Versioned (`-v1`) so a future scheme bump can ship as `-v2` while recovery still tries v1 for older swaps.
120+
- **Tag** — domain-separates this signature from any other use of the descriptor's key. The string is intentionally protocol+provider scoped (`Arkade`+`Boltz`) rather than SDK-scoped, so an Arkade wallet implemented on top of any Arkade SDK (TypeScript, Go, Rust, .NET) can produce the same preimage from the same wallet material and recover swaps the .NET SDK created. Versioned (`-v1`) so a future scheme bump can ship as `-v2` while recovery still tries v1 for older swaps.
121121
- **Descriptor** — scopes the preimage to the specific swap descriptor.
122122
- **Index** — lets a caller derive multiple preimages from the same descriptor. Always `0` today; baked into v1 so recovery iteration is forward-compatible without a scheme bump.
123123

0 commit comments

Comments
 (0)