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 eight 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.

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

All 11 active Loop CI checks passed on 0ad07d71c770, including build/lint, module and generated-file checks, SQLite/PostgreSQL race suites, and LiT unit and integration tests. Current Loop CI

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. That fresh-key case passed locally on tapd v0.8.8 for claim, HTLC timeout, and deposit timeout. The companion PR's current hosted run is incomplete: its default tranche 11 lost communication with the self-hosted runner, which also caused the integration guard to fail. Runner failure

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-10-27T15:06:17Z

@starius: 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.

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

@starius: review reminder

Build the swapkit adapter against the released pre-btcd-v2 modules. Pin tapd's bounded legacy TLV decoder at the v0.8.8 release commit. Map contracts and asset descriptors into SDK plans and reuse the authenticated wallet connection.

Taproot Assets v0.8.8 fixes an asset-invoice settlement regression. Check the running backend before new on-chain operations. Verify proof history, active and passive holdings, Bitcoin anchors and fee prevouts. Keep offline transaction and witness construction available.

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.

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

Reconcile fallback, preimage and refund spends against agreed terms. Recover and export exact proofs, including after ambiguous publication or a restart. Verify against the transaction that actually mined.

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 changed the title ~~assets: Add shared asset tooling~~ assets: Build shared swapkit on tap-sdk Oct 22, 2026

hieblmi force-pushed the codex/shared-asset-swapkit branch from 4807556 to 547a9ad Compare October 22, 2026 10:16

hieblmi changed the title ~~assets: Build shared swapkit on tap-sdk~~ assets: Consolidate shared swap contracts on tap-sdk Oct 22, 2026

hieblmi force-pushed the codex/shared-asset-swapkit branch 7 times, most recently from f50abc0 to f7565a9 Compare October 26, 2026 13:38

hieblmi mentioned this pull request Nov 2, 2026

tapsdk: Maintain the SDK with legacy Bitcoin dependencies #1273

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 added 2 commits November 3, 2026 11:14

swapkit: Share Bitcoin script leaf builders

d84a1b1

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

ef0601a

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.

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

hieblmi added 6 commits November 4, 2026 13:39

tapsdk: Approve transfer plans against agreed terms

1be8836

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: Bind signing to the approved package

9b3167e

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.

tapsdk: Verify presigned descendants through confirmation

9883888

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

tapsdk: Recover claims and refunds from observed spends

0ad07d7

Reconcile fallback, preimage and refund spends against agreed terms. Recover and export exact proofs, including after ambiguous publication or a restart. Verify against the transaction that actually mined.

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

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 Oct 27, 2026

Uh oh!

litbot-9000 commented Nov 3, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hieblmi commented Sep 2, 2026 •

edited

Loading