Skip to content

multi: share transfer sealing with embedders, drop lndclient imports - #2387

Merged
jtobin merged 17 commits into
mainfrom
darioAnongba/embedded-engine-groundwork
Nov 13, 2026
Merged

jtobin merged 17 commits into
mainfrom
darioAnongba/embedded-engine-groundwork

Conversation

@darioAnongba

@darioAnongba darioAnongba commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

An application that embeds Taproot Assets, such as a wallet that runs in a browser, imports asset, proof, tapsend and tappsbt directly. This PR moves the steps of a caller-funded transfer that lived in the RPC server and the asset store into those packages, so that an embedder runs the same code as tapd. It also removes the direct lndclient imports of the core packages.

  • tapsend.ValidateAnchoredPackets and tapsend.CommitPackets hold the input validation and the commit sequence of CommitVirtualPsbts. The RPC server calls both.
  • proof.AppendConfirmedSuffix builds the confirmed proof file of a transfer output and returns it with the completed proof. It leaves the suffix and the input files it is given unchanged, so a failed call can be retried. The asset store calls it.
  • Proof.ToChainAsset derives the anchor commitment the way proof verification does, which leaves the split commitment out of a split output's asset. The merkle root that DecodeProof and VerifyProof report in chain_anchor.merkle_root for a split output is the one its anchor output commits to.
  • Virtual transaction signers take an asset.SignDescriptor, and the lnd-backed signer converts it at the point where it calls lnd. asset.SignVirtualTx and asset.SignOutputRaw live in asset/sign.go, apart from the mock helpers. address.NewTransferFromWalletTx takes an address.WalletTx.
  • make build-wasm compiles the packages an embedder needs for js/wasm, and a CI job runs it.
  • The first commit fixes eleven lint issues in rpcserver/rpcserver.go. The linter checks the lines that are new since a fixed revision, and it counts the whole file as new once git stops detecting its move from rpcserver.go. The file sits at git's rename threshold on main, and the lines this PR takes out of it push it below.

None of asset, tapscript, tapsend and address imports lndclient or lnwallet/btcwallet directly. lndclient remains a transitive dependency through internal/test, which the mock files of these packages import. #2388 removes it. Splitting the courier and archive out of proof is a follow-up.

@coveralls

coveralls commented Nov 11, 2026 •

Copy link
Copy Markdown

Coverage Report for CI Build 43445595716

Coverage increased (+1.5%) to 39.923%

Details

  • Coverage increased (+1.5%) from the base build.
  • Patch coverage: 233 uncovered changes across 12 files (115 of 348 lines covered, 33.05%).
  • 59 coverage regressions across 15 files.

Uncovered Changes

Top 10 Files by Coverage Impact Changed Covered %
tapsend/commit.go 61 0 0.0%
proof/courier.go 53 0 0.0%
asset/assetmock/generators.go 33 0 0.0%
asset/sign.go 70 50 71.43%
rpcserver/rpcserver.go 14 0 0.0%
lndservices/virtual_tx_signer.go 13 0 0.0%
backup/import.go 10 0 0.0%
internal/test/lndmock/keyring.go 10 0 0.0%
proof/proof.go 8 0 0.0%
proof/append.go 48 41 85.42%
Total (18 files) 348 115 33.05%

Coverage Regressions

59 previously-covered lines in 15 files lost coverage.

Top 10 Files by Coverage Loss Lines Losing Coverage Coverage
tapreorg/service.go 30 80.11%
mssmt/compacted_tree.go 5 76.95%
tapdb/interfaces.go 3 66.34%
tapdb/universe.go 3 76.34%
tapgarden/cultivator.go 3 74.1%
asset/mock.go 3 64.8%
address/mock.go 2 86.83%
tapchannel/aux_funding_controller.go 2 30.99%
asset/asset.go 2 56.79%
tappsbt/create.go 1 42.05%

Coverage Stats

Coverage Status
Relevant Lines: 128223
Covered Lines: 51190
Line Coverage: 39.92%
Coverage Strength: 17119.92 hits per line

💛 - Coveralls

@jtobin jtobin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couple of inline comments, otherwise this looks solid.

Comment thread proof/append.go
// inputs it spends are attached to the suffix. An output's inputs are picked
// by the witnesses of its asset, since one anchor transaction can carry
// several independent transitions of the same asset.
func AppendConfirmedSuffix(suffix *Proof, anchorTx *wire.MsgTx,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be better to work with a copy of the suffix so that this one can't wind up partially mut(il)ated in the event of a fetchInput fail in the loop below. Opus considers that a material possibility for an embedder (not for tapd).

VerifyProofSuffix also uses an extra check to ensure the input list order matches. An example replacement for AppendConfirmedSuffix, with both changes:

// AppendConfirmedSuffix completes the transition proof suffix of a transfer
// output with the block that confirmed its anchor transaction. It returns the
// output's full proof file and the completed proof.
//
// The file is that of the output's primary input with the proof appended, and
// the files of any further inputs it spends are attached to the proof. An
// output's inputs are picked by the witnesses of its asset, since one anchor
// transaction can carry several independent transitions of the same asset.
// inputs must list them in the order of the output's virtual packet inputs:
// the first one the asset spends is taken as the primary input.
//
// Neither the suffix nor the files returned by fetchInput are modified, so a
// failed call can be retried with the same arguments.
func AppendConfirmedSuffix(suffix *Proof, anchorTx *wire.MsgTx,
        header wire.BlockHeader, height uint32, merkle TxMerkleProof,
        inputs []asset.PrevID,
        fetchInput func(asset.PrevID) (*File, error)) (*File, *Proof, error) {

        // A pre-broadcast suffix carries no additional inputs. They are
        // attached here, from the input files.
        if len(suffix.AdditionalInputs) != 0 {
                return nil, nil, fmt.Errorf("proof suffix already carries " +
                        "additional inputs")
        }

        witnesses := suffix.Asset.Witnesses()
        var prevIDs []asset.PrevID
        for _, in := range inputs {
                for _, witness := range witnesses {
                        if witness.PrevID != nil && in == *witness.PrevID {
                                prevIDs = append(prevIDs, in)
                        }
                }
        }
        if len(prevIDs) == 0 {
                return nil, nil, fmt.Errorf("no inputs found for output "+
                        "asset %v", suffix.Asset.ID())
        }
        if prevIDs[0].OutPoint != suffix.PrevOut {
                return nil, nil, fmt.Errorf("primary input %v does not "+
                        "match proof suffix previous outpoint %v",
                        prevIDs[0].OutPoint, suffix.PrevOut)
        }

        // We complete a copy of the suffix, so the caller's is unchanged.
        confirmed := *suffix
        confirmed.AnchorTx = *anchorTx
        confirmed.BlockHeader = header
        confirmed.BlockHeight = height
        confirmed.TxMerkleProof = merkle
        confirmed.AdditionalInputs = make([]File, 0, len(prevIDs)-1)

        for _, prevID := range prevIDs[1:] {
                extraFile, err := fetchInput(prevID)
                if err != nil {
                        return nil, nil, err
                }
                confirmed.AdditionalInputs = append(
                        confirmed.AdditionalInputs, *extraFile,
                )
        }

        // The fetched file may be shared, by a cache for example, so we
        // append to a copy of it.
        primaryFile, err := fetchInput(prevIDs[0])
        if err != nil {
                return nil, nil, err
        }
        file, err := cloneProofFile(primaryFile)
        if err != nil {
                return nil, nil, fmt.Errorf("unable to copy primary input "+
                        "proof: %w", err)
        }
        if err := file.AppendProof(confirmed); err != nil {
                return nil, nil, fmt.Errorf("unable to append proof: %w", err)
        }

        return file, &confirmed, nil
}

Comment thread tapdb/freighter_anchoring.go Outdated
}

file, err := fetchInputFile(prevIDs[0])
file, err := proof.AppendConfirmedSuffix(

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the other suggested AppendConfirmedSuffix, this would change à la:

-               file, err := proof.AppendConfirmedSuffix(
+               file, suffix, err := proof.AppendConfirmedSuffix(
                        suffix, anchorTx, header, blockHeight, merkle,
                        inputPrevIDs, fetchInputFile,
                )

@github-project-automation github-project-automation Bot moved this from 🏗 In progress to 👀 In review in Taproot-Assets Project Board Nov 13, 2026
@darioAnongba
darioAnongba force-pushed the darioAnongba/embedded-engine-groundwork branch from e89246a to 1451fab Compare November 13, 2026 12:56
The file carries nine long lines, a redundant conversion and a trailing
newline. The linter checks lines that are new since a fixed revision,
and it counts the whole file as new once git stops detecting the move
of rpcserver.go into its package.
ValidateAnchoredPackets checks committed packets against the anchor
inputs they spend, and CommitPackets seals them into the anchor
transaction. The RPC server calls both, so an embedder runs the same
checks as the daemon.
AppendConfirmedSuffix completes a transfer output's proof suffix with
its confirming block and appends it to the proof file of the input it
spends. The asset store builds confirmed proof files with it, so an
embedder with its own store assembles the same files.
ToChainAsset derives the anchor commitment the way proof verification
does, which leaves the split commitment out of a split output's asset.
The merkle root it reports for a split output is the one its anchor
output commits to.
The signer interfaces of asset and tapscript take an
asset.SignDescriptor, which carries the fields a virtual transaction
signer needs. The lnd-backed signer converts it to the lndclient
descriptor at the point where it calls lnd. A signer can be
implemented without importing lndclient.
SignOutputRaw and SignVirtualTx sign a virtual transaction input with
a raw private key and serve callers that hold their own keys. They
live in sign.go, apart from the mock helpers, so that such callers
depend on a file without test scaffolding.
The custom PSBT input keys that carry a single or double tweak for the
signing key are declared in tapsend with the values of lnd's
lnwallet/btcwallet package. tapsend has no direct import of that
package.
NewTransferFromWalletTx takes an address.WalletTx, which holds the
transaction and its confirmation details. The custodian fills it from
the lnd wallet transaction. Package address has no direct import of
lndclient.
The build-wasm target compiles the packages an embedder needs in the
browser with GOOS=js GOARCH=wasm. A CI job runs it so that platform
specific code in these packages fails the pipeline.
MockSigner and RandCommitmentKeyRing live in internal/test/lndmock and
the gRPC server helpers in internal/test/grpcmock. Package test itself
imports neither lndclient, lnwallet nor grpc, so the packages whose
mock files import it do not link lnd's RPC clients. The unused
ParseRPCKeyDescriptor helper is dropped.
URLDispatch returns a MockProofCourier for the mockcourier address
scheme, so the type is part of the courier code rather than of the
test helpers in mock.go.
WithSkipTimeLockValidationForAllProofs applies to every proof of a
file and to the files of the additional inputs those proofs carry. The
backup pre-verification pass has no chain backend and relies on it for
an asset with a time locked input in its history.
The pre-verification pass of an import skips time lock validation and
must not reach the chain backend. Its chain lookup is a type local to
the package that answers every query with a zero value, so the import
path does not depend on the test helpers of package proof.
RandTapCommitVersion is a test helper, so it lives with the other
random generators. The minting code in mint.go does not import
internal/test.
The property test generators of package asset live in
asset/assetmock. Their package-level initializers instantiate much of
the rapid library, so a production build of asset stays free of that
code. The alt leaf encoding test runs as an external test of asset.
@darioAnongba
darioAnongba force-pushed the darioAnongba/embedded-engine-groundwork branch from 1451fab to 5e423f4 Compare November 13, 2026 13:52
@darioAnongba
darioAnongba requested a review from jtobin November 13, 2026 14:19

@jtobin jtobin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. 👍 👍

@jtobin
jtobin added this pull request to the merge queue Nov 13, 2026
@jtobin
jtobin removed this pull request from the merge queue due to a manual request Nov 13, 2026
…ine-test-deps

multi: keep lndclient out of the core package mocks
@jtobin
jtobin enabled auto-merge November 13, 2026 14:44

@GeorgeTsagk GeorgeTsagk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

@jtobin
jtobin added this pull request to the merge queue Nov 13, 2026
Merged via the queue into main with commit 18e87e3 Nov 13, 2026
83 of 84 checks passed
@github-project-automation github-project-automation Bot moved this from 👀 In review to ✅ Done in Taproot-Assets Project Board Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: ✅ Done

Development

Successfully merging this pull request may close these issues.

4 participants