HTLC lifecycle (create / redeem / refund) signing from a third-party dApp — current API gap

[Andjroo111]

Hi team — following up on nimiq/wallet#293 (HTLC SDK methods for Nimiq Pay mini-apps), filing this in the Hub repo because the gap is Hub-specific and current. I'm shipping a non-Oasis HTLC dApp on Nimiq mainnet (hash.market — an HTLC-backed peer-to-peer prediction market) and ran into a hard upstream block on three connected lifecycle operations. Posting concrete repro + code references so it's actionable rather than a vague "Hub doesn't support X."

Context. Phase 1 of the project drove the full HTLC lifecycle (create → redeem → refund) on mainnet from a CLI built on @nimiq/core v2.5.0 — hand-built recipient_data, RegularTransfer, and TimeoutResolve proofs (ref: primitives/transaction/src/account/htlc_contract.rs). Wire format byte-verified via HashedTimeLockedContract.dataToPlain() / proofToPlain(). Four mainnet txs included on first attempt. Wire format works.

The block hits when porting to a browser dApp where keys live in Hub.

---

Block 1 — HTLC creation via SIGN_TRANSACTION is rejected by both layers.

The natural shape is:

hub.signTransaction({
  appName, sender, recipient: <computed contract address>,
  recipientType: AccountType.HTLC,                  // 2
  flags: TransactionFlag.ContractCreation,          // 1
  extraData: <82 bytes of creation_data>,
  value, fee, validityStartHeight,
});

What actually happens:

1. Hub RequestParser.ts parses recipient via Nimiq.Address.fromString(...) (src/lib/RequestParser.ts, inside the RequestType.SIGN_TRANSACTION branch). No special-case for the magic string 'CONTRACT_CREATION'.
2. Keyguard RequestParser.js then validates: when flags === ContractCreation, recipient MUST equal the literal string 'CONTRACT_CREATION', otherwise it throws (src/lib/RequestParser.js, parseTransaction()):

   if (flags === Nimiq.TransactionFlag.ContractCreation && recipient !== 'CONTRACT_CREATION') {
       throw new Errors.InvalidRequestError(
           'Transaction recipient must be "CONTRACT_CREATION" when creating contracts',
       );
   }

This is a catch-22. Pass the computed contract address → Keyguard rejects with the error above. Pass the literal string 'CONTRACT_CREATION' → Hub's parser fails on Nimiq.Address.fromString('CONTRACT_CREATION') before reaching Keyguard. Hub silently closes / redirects back without UI.

Internal Hub code paths do construct recipient: 'CONTRACT_CREATION' for Keyguard — SETUP_SWAP's NIM funding leg is the proof that the underlying mechanism works. It's the public SIGN_TRANSACTION entry point that doesn't surface it.

Block 2 — RegularTransfer redemption.

Sender = HTLC contract, recipient = basic account, proof = [discriminant, hash_depth, hash_root, preimage, signature_proof]. The signature covers tx.serializeContent() only — the proof bytes themselves aren't signed. So the primitive needed is essentially "sign tx-content bytes with the recipient's keypair, then stitch the proof together."

SETUP_SWAP does this internally for its redeem leg, but the public SIGN_TRANSACTION request doesn't accept the HTLC sender shape (nor would it know how to build the proof). SIGN_MESSAGE prepends "Nimiq Signed Message:\n", so it can't substitute.

Block 3 — TimeoutResolve refund.

Same primitive as redemption, simpler proof ([discriminant, signature_proof]). Same gap.

---

Three possible paths I see:

• (A) Same-asset SETUP_SWAP. Pass fund = NimiqHtlcCreationInstructions, redeem = NimiqHtlcSettlementInstructions with both legs type: 'NIM', even though there's no real swap. Hub already signs all three lifecycle txs upfront in this flow and returns redeem + refund as pre-signed templates. Loose semantic fit but might "just work"?

• (B) Wait for nimiq/wallet#293. When HTLC SDK methods land in @nimiq/mini-app-sdk, Pay mini-apps get this directly. If @nimiq/core v2.6+ exposes them too, full in-browser signing without Hub becomes possible. Long-term answer might be "not via Hub at all."

• (C) New Hub request type(s). A SIGN_HTLC_CREATE / SIGN_HTLC_REDEEM / SIGN_HTLC_REFUND trio (or one SIGN_HTLC_LIFECYCLE with a discriminant). Wraps the existing internal primitives. Additive — wouldn't break anything. Would also unblock escrow, freelance-milestone, ticket-resale, and domain-transfer dApps that hit the same wall.

Workaround we'll ship in the meantime.

Until one of (A)/(B)/(C) lands, we plan to derive an ephemeral signing key per market+side from a SIGN_MESSAGE signature on the user's main address (deterministic + recoverable + no custody). The user signs once via Hub, we derive the ephemeral key, the user funds the ephemeral address with a normal SIGN_TRANSACTION, then we sign HTLC creation / redemption / refund locally using the ephemeral key. Real on-chain HTLCs, no custody, but two Hub popups + one extra tx + ~30s confirmation wait per bet. We'll publish this pattern when we ship — the next non-Oasis HTLC dApp on Nimiq is going to hit this same wall.

A few questions for the team:

1. Is (A) the intended-but-undocumented pattern today? Does Hub accept fund and redeem of the same type: 'NIM' against the same hash root? If yes, we'll integrate and document.
2. Is (B) the right mental model long-term? That this surface eventually moves out of Hub into @nimiq/core direct usage once SDK methods land?
3. Would you take a community PR for (C)? Internal primitive already exists; it's a public API surface question. Happy to draft against the architecture you'd want.

For context on the use case: each YES/NO position in hash.market locks in its own HTLC, multisig oracle reveals the preimage at resolution. Phase 1 mainnet validation and Phase 2 architecture are public.

Thanks for Hub — it's load-bearing for getting more HTLC-native dApps shipping on Nimiq.

—

[Andjroo111]

Quick update with mainnet evidence — the ephemeral-key workaround referenced in the OP is now running end-to-end. Posting the concrete tx hashes since they might help when you evaluate which of paths A/B/C makes sense.

Drove the full HTLC lifecycle on Nimiq mainnet — creation, RegularTransfer redemption, and TimeoutResolve refund — entirely via in-browser local signing, with Hub only doing SIGN_MESSAGE and a plain SIGN_TRANSACTION for funding.

Matched-bet settlement (market 019e1521-6c80-78f6-800c-898de337eca5):

• Oracle key: Hub.signMessage("hashmark-oracle-v1:<marketId>") → HKDF-SHA256 → Ed25519 keypair → ephemeral oracle address, stored as the HTLC recipient so the creator re-derives it and signs RegularTransfer proofs locally at settlement.
• HTLC YES creation: 4d0dc9e2c55d438f3ba1ef6a2522c8ec85695e19d7c5784b1f78b655409f867b — sender = ephemeral YES bet key from Hub.signMessage("hashmark-stake-v1:<marketId>:yes"), 82-byte creation data, recipientType: HTLC, signed locally.
• HTLC NO creation: c2a716437176db35f9245280d47ded5a25d408920043eba978070fc13bb5daab
• HTLC YES redemption (RegularTransfer): 850b8453e2e3f73c2718b8da7c339d41d3d4b543335b4a5d09a86c2e30c97922 — proof = [discriminant, hash_depth, algo_tag, hash_root, preimage_len, preimage, signature_proof], signature over tx.serializeContent() by the ephemeral oracle keypair, preimage read off-chain.
• HTLC NO redemption (RegularTransfer): 4b0653fe261c1593ed244ee69902f2ffcb7bdab03cb921ce3fa8730a7a8147ba

TimeoutResolve refund (separate market 019e14e5-7d87-7000-ba23-6c68cdec2195 — a 1-NIM bet that timed out unmatched):

• HTLC creation: bettor's ephemeral key, recipient = market creator, timeout = market deadline.
• Refund: 7609136c23876d8fe1344620fce98bac477833b1cc31d04273715ab0813d647c — TimeoutResolve proof = [discriminant, signature_proof], signed locally with the re-derived ephemeral key after the timeout block.

So all the OutgoingHTLCTransactionProof variants in primitives/transaction/src/account/htlc_contract.rs are constructible from a browser dApp and accepted on mainnet — RegularTransfer and TimeoutResolve exercised here; EarlyResolve not yet, but it's the same keyPair.sign(tx.serializeContent()) + SignatureProof.singleSig(...).serialize() pattern, just two signatures stitched together.

Hub calls for the whole lifecycle: SIGN_MESSAGE per key derivation + SIGN_TRANSACTION per ephemeral-address funding. Zero SIGN_TRANSACTION calls had recipientType: HTLC or an HTLC sender — Hub never sees an HTLC transaction.

Architecture is locked at ADR-0014 (oracle side) and ADR-0013 (bettor side).

On the three paths from the OP:

• (A) same-asset SETUP_SWAP — didn't try it; the ephemeral path landed first because it's narrower and doesn't require pretending the swap is real. Happy to test (A) on a branch if it's the pattern you'd document.
• (B) nimiq/wallet#293 — confirmed long-term answer. If HTLC methods land in @nimiq/core v2.6+ (not just the mini-app SDK), this workaround disappears in favor of direct in-browser signing with Hub-derived keys (≈150 LOC + one Hub round-trip per bet gone).
• (C) SIGN_HTLC_* Hub request types — still my preferred near-term path. The internal primitives clearly exist (SETUP_SWAP's NIM legs use them); the gap is the public SIGN_TRANSACTION surface. PR scope ≈ three request types in RequestParser + three handlers in Keyguard mirroring SIGN_TRANSACTION. Happy to draft against the shape you'd want — would also unblock escrow / freelance-milestone / ticket-resale / domain-transfer dApps that hit the same wall.

Side observation, maybe worth its own issue. Hub's mobile redirect returns the response to the dApp origin with referrer = keyguard.nimiq.com, but hub-api's response handler strictly checks the referrer against hub.nimiq.com — so on mobile redirect, the response is silently discarded by hub-api. We work around it by parsing the URL fragment ourselves and dispatching the response manually (safe because the payload is cryptographically self-validating). Not this issue, but adjacent.

Code's MIT, public at Andjroo111/hashmark:

• app/src/client/bet-key.ts / app/src/client/oracle-key.ts — HKDF derivation, bettor + creator sides
• app/src/client/main.ts — handleResolveReturn (local RegularTransfer construction), handleRefundReturn (local TimeoutResolve construction)
• app/src/client/wire/htlc.ts — wire-format serializers, ported from a CLI that byte-verified against HashedTimeLockedContract.dataToPlain() / proofToPlain()

Thanks for Hub — SIGN_MESSAGE behaving deterministically (RFC-8032 Ed25519, same message → same signature → reproducible seed) was the unlock that made the whole workaround viable.