swapkit: Consolidate asset swaps on tap-sdk v0.1.1 by hieblmi · Pull Request #1225 · lightninglabs/loop

hieblmi · 2026-09-02T14:07:57Z

Provide shared contracts and SDK helpers for asset Loop In, asset Loop Out, and reservations. swapkit/ defines Bitcoin spending policies, signing roles, witnesses, and weights. swapkit/tapsdk/ adapts those contracts to native tap-sdk transfer construction, checks independently agreed terms, binds signing to the approved package, and handles proofs and recovery. The consuming feature owns its state machine, persistence, Lightning deadlines, and decisions about releasing signatures or preimages.

The implementation uses released tap-sdk v0.1.1 and Taproot Assets v0.8.8 on the pre-btcd-v2 dependency graph. New on-chain asset operations require a running tapd v0.8.8. The runtime gate accepts the released daemon's 0.8.8-alpha version string and rejects v0.8.6, v0.8.7, and v0.8.8 release candidates. Consuming Go modules must repeat the bounded legacy TLV decoder replacement in Loop's go.mod, because Go does not inherit dependency replacements.

All contracts have a cooperative MuSig2 path. Their unilateral refund policies are explicit:

Constructor	Refund policy
`NewDepositKit`	Sender CSV delay measured from funding confirmation
`NewReservationKit`	Server/sender absolute CLTV height
`NewSwapKit(SwapHTLCLegacyCSV)`	Sender CSV delay
`NewSwapKit(SwapHTLCStaticLoopInV3)` / `SwapHTLCCLTV`	Sender absolute CLTV height

Both HTLC variants require the receiver's signature and the correct 32-byte preimage on success, with the existing one-block CSV. The reservation purchase flow in Loop #1229 preserves its quoted CSV delay by adapting NewDepositKit with explicit server/client key roles. NewReservationKit supplies the separate CLTV policy.

The default asset script descriptor preserves the fixed NUMS internal key and single OP_TRUE leaf through LegacyOPTrueOutput. The SDK supplied-key variant, SDKOPTrueOutput, requires explicit selection. Funded outputs retain their exact descriptors through spending and recovery.

Review the nine commits in order. Each carries unit coverage for the behavior it introduces.

Share Bitcoin leaf serializers with existing swaps, preserving byte-for-byte script encodings and quote templates.
Define deposit, reservation, and HTLC contracts, signing roles, witnesses, and weights.
Connect the released SDK to an authenticated tapd connection and map contracts and asset descriptors to SDK requests.
Enforce the tapd version floor and authenticate asset history and Bitcoin prevouts against the current chain.
Check the native builder's transaction, asset allocations, and fees against independently agreed terms.
Bind signing authority and final witnesses to the approved native package.
Verify presigned descendants against their parents and carry them through confirmation.
Recover claims, refunds, and exact output proofs from observed spends.
Harden recovery against hostile peer input: bind a recovery fallback to the authenticated deposit before co-signing, verify a caller-provided asset witness before declaring it, and classify annex spends, reorgs, and stale chain responses in the observed-spend helpers.

Package usage and validation boundaries are documented in the contract README and SDK adapter README.

Rebased on Loop master 9158aed2a. Unit tests for every package this PR touches passed locally on d620bd25aca7, the swapkit and proof/policy suites also under the race detector. Lint reported no findings in the files this PR touches, and the commit-message and module tidiness checks passed. CI for this head is running.

Daemon-backed asset lifecycle tests live in Nautilus #1712. They cover the contracts, transfer and proof boundaries, and an explicitly selected SDK supplied-key OP_TRUE deposit-to-HTLC lifecycle. The server pins this head at c0f4ef6d0. The fresh-key case (claim, HTLC timeout, and deposit timeout) and the deposit HTLC timeout sweep, kit restart recovery, recovery respend, passive asset, split transfer, reorg proof, and asset HTLC cases passed locally on tapd v0.8.8 on a build containing this head's kit changes, before its last rebase onto Loop master. Companion CI runs them on the pinned head.

hieblmi · 2026-09-03T12:29:54Z

/gateway review

lightninglabs-gateway · 2026-09-03T12:30:15Z

👀 gateway review starting…

starius

Style — ~18 unexported funcs and ~14 test helpers have no godoc, against the convention. Non-test: canonicalAddressParams, cloneAddressParams (both copies), validateScripts, genBtcControlBlock, validateAsset (both), findUniqueInput (both), validateSweep (both), validateSequence, verifyTapscriptSignature (both), timeoutPathSibling, encodedTimeoutPathSibling, newHtlcSwapKit, validateProof.

hieblmi · 2026-09-08T12:44:30Z

Follow-up commit 818876e also adds documentation to the unexported production and test helpers listed in the general review. Local verification passed: go test ./..., go test -race ./assets/..., go vet ./..., golangci-lint (0 issues), plus a Nautilus #1712 itest-package compile with integration tags.

litbot-9000 · 2026-09-17T06:06:39Z

@bhandras: review reminder
@sputn1ck: review reminder
@hieblmi, remember to re-request review from reviewers when ready

litbot-9000 · 2026-09-24T07:04:25Z

@hieblmi, remember to re-request review from reviewers when ready

litbot-9000 · 2026-11-03T15:16:36Z

@starius: review reminder

litbot-9000 · 2026-11-10T16:45:11Z

@starius: review reminder
@bhandras: review reminder

Route existing HTLC, static address and reservation scripts through the same leaf serializers. Pin the quote templates so moving the serialization cannot change signed numbers or zero-hash fee estimates.

Define the key roles, cooperative and unilateral paths, witnesses and weight estimates for both directions. Exercise the legacy vectors and execute the spend conditions against the Bitcoin script engine.

Build the adapter against released pre-btcd-v2 modules and retain the bounded legacy TLV decoder. Map contracts into SDK plans and reuse the authenticated wallet connection. Define the shared runtime version floor and operation-scoped checks. Warn about older backends during daemon initialization while leaving ordinary payments and offline witness construction available.

Authenticate proof history, asset commitments, group issuances and Bitcoin inputs before granting on-chain authority. Apply the shared tapd floor at proof boundaries while keeping offline construction available. Distinguish invalid funding candidates from exact outputs waiting on confirmations or a chain backend. Preserve retryable results when no candidate is ready.

Prepare confirmed inputs for native Build and check its allocations, Bitcoin template, change policy and fee before granting authority. Verify wallet-funded fees again after native Commit.

Check signing policy and the saved package before using LND, and accept peer witnesses only for the approved transaction. Preserve durable recovery while ephemeral signing sessions remain caller-owned. Separate contract-input signing from finalization so wallet-funded callers can sign fee inputs before sealing the final anchor transaction.

Bind native compact paths to approved signed parents. After parents confirm, replace proof metadata with authenticated histories without altering the transaction or final witnesses.

Recover contract spends through native SDK packages and exact output proofs. Preserve the original contract descriptors, asset quantities and confirmation evidence across claims and refunds. Make publication retries consult exact archived proofs and the tapd transfer log before logging again. Report pending confirmations without creating duplicate transfer records or repeating their anchor fees.

Bind a recovery fallback package to the authenticated deposit before it is co-signed. The MuSig2 sighash covers the committed PSBT's own previous output, so a peer that changed only the signed input value or script obtained a valid signature that spent nothing real. Compare that prevout with the deposit output, reject a committed asset that carries its own lock time, and require normal broadcast. Verify a caller-provided asset witness commits to its input script key before declaring it to tapd, so a peer cannot bind a wallet script key to an unrelated internal key. Recognize a BIP-341 annex when matching the agreed leaf, reject an annex spend from reconstruction rather than mis-slicing its witness, report a reorg observed during outcome verification as retryable, and guard the observed-spend discovery helpers against a chain that returns a block without the watched spend.

GustavoStingelin

Found no issues.

hieblmi added the no-changelog Skip the release notes CI check label Sep 2, 2026

hieblmi force-pushed the codex/shared-asset-swapkit branch 4 times, most recently from c206f0d to 2814bf6 Compare September 3, 2026 05:54

hieblmi added asset loop out Taproot Asset Loop Out work and removed no-changelog Skip the release notes CI check labels Sep 3, 2026

hieblmi changed the title ~~assets: Add shared asset HTLC kit~~ assets: Add shared asset tooling Sep 3, 2026

hieblmi added the no-changelog Skip the release notes CI check label Sep 3, 2026

hieblmi force-pushed the codex/shared-asset-swapkit branch 2 times, most recently from 4283082 to 50595de Compare September 3, 2026 08:12

hieblmi self-assigned this Sep 3, 2026

hieblmi marked this pull request as ready for review September 3, 2026 12:22

hieblmi requested review from bhandras, sputn1ck and starius September 3, 2026 12:24

starius reviewed Sep 3, 2026

View reviewed changes

hieblmi requested a review from starius September 8, 2026 13:05

hieblmi force-pushed the codex/shared-asset-swapkit branch from 818876e to 81e876c Compare September 8, 2026 14:33

starius reviewed Sep 9, 2026

View reviewed changes

Comment thread assets/deposit/kit.go Resolved

starius reviewed Sep 10, 2026

View reviewed changes

hieblmi mentioned this pull request Sep 15, 2026

assets/reservation: Add client-initiated reservation purchases #1229

Open

1 task done

hieblmi force-pushed the codex/shared-asset-swapkit branch from 81e876c to dcd5af1 Compare September 17, 2026 08:44

hieblmi requested a review from GeorgeTsagk September 24, 2026 12:08

hieblmi mentioned this pull request Sep 24, 2026

[asset loop out 1/x] assets: add tapkit #960

Closed

hieblmi force-pushed the codex/shared-asset-swapkit branch from f7565a9 to 4a124f3 Compare November 2, 2026 16:05

hieblmi changed the title ~~assets: Consolidate shared swap contracts on tap-sdk~~ swapkit: Consolidate asset swaps on the local Taproot Assets SDK Nov 2, 2026

darioAnongba mentioned this pull request Nov 2, 2026

multi: backport #187 and #188 for v0.1.1 lightninglabs/tap-sdk#191

Merged

hieblmi force-pushed the codex/shared-asset-swapkit branch from 4a124f3 to a6b6846 Compare November 2, 2026 20:49

hieblmi changed the title ~~swapkit: Consolidate asset swaps on the local Taproot Assets SDK~~ swapkit: Consolidate asset swaps on tap-sdk v0.1.1 Nov 2, 2026

hieblmi force-pushed the codex/shared-asset-swapkit branch 2 times, most recently from 8347df9 to 941c126 Compare November 3, 2026 13:08

hieblmi force-pushed the codex/shared-asset-swapkit branch from 941c126 to 0ad07d7 Compare November 4, 2026 13:41

hieblmi requested a review from bhandras November 5, 2026 13:18

hieblmi force-pushed the codex/shared-asset-swapkit branch 5 times, most recently from dc2961f to 34cd8d2 Compare November 10, 2026 12:38

hieblmi force-pushed the codex/shared-asset-swapkit branch 2 times, most recently from 9dc4039 to 7d29edd Compare November 11, 2026 13:36

hieblmi added 9 commits November 12, 2026 17:06

swapkit: Share Bitcoin script leaf builders

5a984e4

Route existing HTLC, static address and reservation scripts through the same leaf serializers. Pin the quote templates so moving the serialization cannot change signed numbers or zero-hash fee estimates.

swapkit: Define asset deposit, reservation and HTLC contracts

749c8aa

Define the key roles, cooperative and unilateral paths, witnesses and weight estimates for both directions. Exercise the legacy vectors and execute the spend conditions against the Bitcoin script engine.

tapsdk: Approve transfer plans against agreed terms

d464aa5

Prepare confirmed inputs for native Build and check its allocations, Bitcoin template, change policy and fee before granting authority. Verify wallet-funded fees again after native Commit.

tapsdk: Verify presigned descendants through confirmation

9e4c1e6

Bind native compact paths to approved signed parents. After parents confirm, replace proof metadata with authenticated histories without altering the transaction or final witnesses.

hieblmi force-pushed the codex/shared-asset-swapkit branch from 7d29edd to d620bd2 Compare November 12, 2026 16:17

GustavoStingelin self-requested a review November 13, 2026 13:23

GustavoStingelin approved these changes Nov 13, 2026

View reviewed changes

Conversation

hieblmi commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hieblmi commented Sep 3, 2026

Uh oh!

lightninglabs-gateway Bot commented Sep 3, 2026

Uh oh!

starius left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hieblmi commented Sep 8, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

litbot-9000 commented Sep 17, 2026

Uh oh!

litbot-9000 commented Sep 24, 2026

Uh oh!

litbot-9000 commented Nov 3, 2026

Uh oh!

litbot-9000 commented Nov 10, 2026

Uh oh!

GustavoStingelin left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

hieblmi commented Sep 2, 2026 •

edited

Loading