mini-app-sdk: expose HTLC-aware staking — Pay's wallet can fund stakes from swap contracts (verified)

[subimpact]

Feature request: let mini-apps stake NIM that's in transit through HTLC contracts

Summary

@nimiq/mini-app-sdk exposes staking methods (sendNewStakerTransaction, sendStakeTransaction, ...) that are forwarded to the Nimiq Pay wallet, which decides how to fund them. We discovered (and verified on-chain, 2026-09-10) that Pay's wallet CAN fund a stake from an HTLC swap contract — but only if the mini-app asks it to. The SDK gives no way to express "stake from my in-transit funds", and the app-side balance APIs give no way to know it's possible.

What we verified

• Nimiq Pay routes transfers through HTLC contracts (sender = the app-facing relay address, recipient = Pay's swap service, hashRoot all-zeros = timelock-only custody, no preimage).
• The relay's basic balance is effectively always 0 — every settlement is re-locked into a fresh contract within seconds.
• Calling sendStakeTransaction anyway (with the app's stake ceiling set to basic + in-transit) worked: the wallet redeemed 100 NIM directly from the HTLC contract to fund the stake. Contract balance dropped exactly 100 NIM, staker record went active, basic balance stayed 0.
• This is the only way a mini-app can stake from inside Pay — and it's currently undocumented and undiscoverable.

What would help

1. Document the behavior: "staking requests may be funded from HTLC in-transit funds at the wallet's discretion" — so mini-apps can set their stake ceilings to basic + in-transit without guessing.
2. A balance API that includes in-transit funds (e.g. getBalances() returning { basic, htlcInTransit, staked, ... }) so apps don't have to crawl contracts themselves.
3. An explicit funding hint on staking requests (e.g. allowInTransitFunding: boolean) so the wallet can confirm with the user when it redeems a contract.

Context

• Competition entry: NimBooks (https://nimbooks.subimpact.net) — shipped the workaround (stake ceiling = basic + in-transit) and verified it live.
• Related: #293 (nimiq/wallet) — HTLC transaction methods timeline; "NIM core parity (send/receive/stake/HTLC in Pay)" per the Nov 2025 roadmap reply.

Happy to provide the on-chain tx evidence or test a proposed API on-device.

[sisou]

Yes. Currently, a user's funds are all sent to an HTLC, which we call "remote account". It's not in-transit, though. It's stored there and released/redeemed whenever the user wants to make a payment or gets triggered by mini-apps sendTransaction, etc methods through co-signing with the HTLC "recipient" (early-redeem).

So yeah, if you want to know the user's complete balance, you need to check the balances for both addresses returned in provider.listAccounts().

Where do you propose this should be documented, that the funds are coming from the HTLC, and not the base account?

[subimpact]

Thanks @sisou — that's exactly the clarification we needed, and the listAccounts() hint is gold: we were scanning the chain for HTLC contracts via RPC; using the second address from listAccounts() is a much cleaner way to get the remote account.

Proposed documentation spots:

1. SDK JSDoc on listAccounts() — note it returns both the base and remote (HTLC) account, and that the remote account holds the user's stored funds
2. Mini-apps docs — a short "Balances" section: base vs remote account, and that staking/payment requests may be funded from either at the wallet's discretion
3. SDK README — one line under the provider API

We'll adopt the remote-account balance in NimBooks and align our copy with the correct terminology.