Skip to content

embedded: add an in-process transport - #197

Merged
darioAnongba merged 8 commits into
mainfrom
darioAnongba/embedded-engine
Nov 13, 2026
Merged

darioAnongba merged 8 commits into
mainfrom
darioAnongba/embedded-engine

Conversation

@darioAnongba

@darioAnongba darioAnongba commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

The embedded package is a third transport next to grpc and rest. It implements tapsdk.Client inside the host process, so a wallet can hold, verify and move Taproot Assets with no tapd and no lnd beside it. The host supplies three ports: a Store for keys, proof files and transfers, a KeyRing (lnd's keychain.SecretKeyRing fits) and a Chain for block headers, broadcast and confirmations.

The engine implements the subset of tapd's gRPC services a wallet needs and serves it over an in-process connection, under the existing gRPC client code. Both backends therefore share request validation, marshalling and error statuses. Every asset rule is a call into tapd's packages; the engine adds storage and the order of the calls.

  • Proofs. VerifyProof checks a file against the chain port's headers and the trusted asset groups. InsertProof followed by RegisterTransfer imports a received asset, so Wallet.ImportProofFile works unchanged.
  • Keys. Script keys and anchor internal keys derive from the key ring under the requested family and are recorded in the store.
  • Balances. ListBalances sums the wallet's unspent outputs by asset ID or by group key. The engine has no universe, so Wallet.GetBalance and Wallet.ListBalances treat an asset as known when the wallet holds or has spent an output of it.
  • Transfers. SignVirtualPsbt, CommitVirtualPsbts and PublishAndLogTransfer cover the custom-anchor flow for caller-funded anchor transactions, including signing the anchor inputs the wallet owns. A transfer is recorded before it is broadcast. The engine writes the final proofs when the anchor transaction confirms, follows it through re-orgs, and resumes after a restart.
  • Capabilities. The client reports BackendLightweight, supports backend anchor signing and local verification, and reports wallet funding as unsupported, since the engine holds no Bitcoin.
  • Everything else returns codes.Unimplemented: minting, universe queries, address sends, burns and event streams.

The package builds for js/wasm, and make unit-wasm with its CI job runs the engine's tests there. docs/design/embedded-transport.md records the design.

go.mod pins tapd main, which carries the helpers the engine calls (lightninglabs/taproot-assets#2387). #198 runs the engine against tapd in the itest stack.

The embedded engine calls tapsend.ValidateAnchoredPackets,
tapsend.CommitPackets and proof.AppendConfirmedSuffix, and signs with
asset.SignDescriptor.
NewClientFromConn builds the gRPC client over an established
connection, such as an in-process one, and sends no macaroons.
The embedded transport takes what a tapd would take from lnd and its
database through three ports. MemoryStore is a store for tests, and
localConn routes gRPC calls to services in the same process.
The engine answers the tapd calls a wallet needs inside the host
process: proof verification, asset keys, owned outputs, and the
signing, sealing and publishing of caller-funded transfers. It writes
the final proofs once an anchor transaction confirms, follows it
through re-orgs and resumes after a restart.
The engine runs in browsers, so its tests also run under Node with
GOOS=js GOARCH=wasm.
GetBalance and ListBalances probe the universe to tell a known asset
with no balance from an unknown one. When the backend answers the probe
with Unimplemented, the wallet's own records decide: an asset it holds
or has spent is known.
The engine sums the wallet's unspent asset outputs by asset ID or by
group key, with tapd's filters and its count of pending transfers.
Wallet.GetBalance and Wallet.ListBalances work on the embedded
transport.
@darioAnongba
darioAnongba force-pushed the darioAnongba/embedded-engine branch from a927e53 to 2c48bcd Compare November 13, 2026 17:23
@darioAnongba
darioAnongba merged commit 31cf407 into main Nov 13, 2026
6 checks passed
@github-project-automation github-project-automation Bot moved this from 🏗 In progress to ✅ Done in Taproot-Assets Project Board Nov 13, 2026
@darioAnongba
darioAnongba deleted the darioAnongba/embedded-engine branch November 13, 2026 18:49
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.

1 participant