Database Migrations

tapd v0.5.0 contains non-revertible database migrations. After running tapd v0.5.0, these database migrations prevent downgrading tapd to a previous release. Create backups of tapd database state, before upgrading to tapd v0.5.0. Please report any database migration issues.

Breaking changes

Downstream Projects - `litd`

litd v0.14.0-alpha enhancements require both channel peers to upgrade to a litd version >= v0.14.0-alpha to continue Lightning Channel functionality. See upgrade instructions below if you opened Asset channels with such an experimental version.

`tapd` `v0.5.0` changes

Oracle RPC:
The RPC protobuf definitions for the Price Oracle have changed. Asset exchange rates are now expressed as FixedPoint to achieve better precision.
The rationale for the change and the new math behind it are described in the new RFQ document.
Code examples for a Price Oracle server are available here.

Configuration changes:
The configuration value (universe.public-access) and command line flag (--universe.public-access) now needs a value and is no longer a boolean. The value now controls whether the node's universe database can be accessed over RPC and either read (value r) or written to (value w) or both (value rw).
So existing nodes with the configuration file value universe.public-access=true need to change the value to universe.public-access=rw. Users specifying the command line flag --universe.public-access just need to append a value, for example --universe.public-access=rw.

⚠️ CRITICAL INSTRUCTIONS ⚠️:

Required-upgrade path for existing `litd` installations:

To avoid loss of channel funds: Any litd node which ran Taproot Asset channels using any litd v0.13.9xx-experimental versions MUST FOLLOW all of the following procedures:
litd v0.14.0-alpha enhancements require both channel peers to upgrade to a litd version >= v0.14.0-alpha to continue Lightning Channel functionality.
If one channel peer is running litd version <= v0.13.9xx-experimental channel operations are are NOT forwards compatible with litd v0.14.0-alpha versions.

All Taproot-Asset Lightning channels created using litd version <=, v0.13.9xx-experimental must be cooperatively closed before upgrading to v0.14.0-alpha.
- Channel Closure instructions
- Monitor status of lncli pendingchannels: Ensure pending_htlcs response is empty before progressing
  Example: lncli listchannels | jq '.channels[] | select(.pending_htlcs != [])'
Avoid force closing the channels. If there are pending/in-flight HTLCs, wait for HTLCs to be resolved.
Once all channels are fully closed (e.g. lncli pendingchannels is empty), both nodes must be upgraded to the new v0.14.0-alpha version before new channels can be opened. Please coordinate the upgrade with your peer if you're not operating both nodes.
Daemon installations which exclusively contain Taproot Assets on-chain outputs that are not contained within lightning channels, are not required to follow this upgrade path. Anything mentioned above only relates to assets in channels. Normal on-chain assets are not affected.

Verifying the Release

In order to verify the release, you'll need to have gpg or gpg2 installed on your system. Once you've obtained a copy (and hopefully verified that as well), you'll first need to import the keys that have signed this release if you haven't done so already:

curl https://raw.githubusercontent.com/lightninglabs/taproot-assets/main/scripts/keys/roasbeef.asc | gpg --import

Once you have the required PGP keys, you can verify the release (assuming manifest-roasbeef-v0.5.0.sig and manifest-v0.5.0.txt are in the current directory) with:

gpg --verify manifest-roasbeef-v0.5.0.sig manifest-v0.5.0.txt

You should see the following if the verification was successful:

gpg: Signature made Wed Sep 30 17:35:20 2020 PDT
gpg:                using RSA key 60A1FA7DA5BFF08BDCBBE7903BBD59E99B280306
gpg: Good signature from "Olaoluwa Osuntokun <laolu32@gmail.com>" [ultimate]

That will verify the signature of the manifest file, which ensures integrity and authenticity of the archive you've downloaded locally containing the binaries. Next, depending on your operating system, you should then re-compute the sha256 hash of the archive with shasum -a 256 <filename>, compare it with the corresponding one in the manifest file, and ensure they match exactly.

Verifying the Release Timestamp

In addition to time-stamping the git tag with OpenTimestamps, we also timestamp the manifest file along with its signature. Two files are included in our release artifacts: manifest-roasbeef-v0.5.0.sig.ots and manifest-v0.5.0.txt.ots.

Assuming you have the opentimestamps client installed locally, the timestamps can be verified with the following commands:

ots verify manifest-roasbeef-v0.5.0.sig.ots -f manifest-roasbeef-v0.5.0.sig
ots verify manifest-v0.5.0.txt.ots -f manifest-v0.5.0.txt

Alternatively, the OpenTimestamps website can be used to verify these timestamps if one doesn't have a bitcoind instance accessible locally.

Assuming you are using the OpenTimestamps ots-git-gpg-wrapper you can verify the timestamp of the git tag by verifying the tag as explained in Verifying the Release Binaries.

These timestamps should give users confidence in the integrity of this release even after the key that signed the release expires.

Verifying the Release Binaries

Our release binaries are fully reproducible. Third parties are able to verify that the release binaries were produced properly without having to trust the release manager(s). See our reproducible builds guide for how this can be achieved.
The release binaries are compiled with go1.22.6, which is required by verifiers to arrive at the same ones.

The make release command can be used to ensure one rebuilds with all the same flags used for the release. If one wishes to build for only a single platform, then make release sys=<OS-ARCH> tag=<tag> can be used.

Finally, you can also verify the tag itself with the following command:

$ git verify-tag v0.5.0
gpg: Signature made Tue Sep 15 18:55:00 2020 PDT
gpg:                using RSA key 60A1FA7DA5BFF08BDCBBE7903BBD59E99B280306
gpg: Good signature from "Olaoluwa Osuntokun <laolu32@gmail.com>" [ultimate]

Verifying the Docker Images

To verify the tapd and tapcli binaries inside the docker images against the signed, reproducible release binaries, there is a verification script in the image that can be called (before starting the container for example):

$ docker run --rm --entrypoint="" lightninglabs/taproot-assets:v0.5.0 /verify-install.sh v0.5.0
$ OK=$?
$ if [ "$OK" -ne "0" ]; then echo "Verification failed!"; exit 1; done
$ docker run lightninglabs/taproot-assets [command-line options]

Building the Contained Release

Users are able to rebuild the target release themselves without having to fetch any of the dependencies. In order to do so, assuming
that vendor.tar.gz and tapd-source-v0.5.0.tar.gz are in the current directory, follow these steps:

tar -xvzf vendor.tar.gz
tar -xvzf tapd-source-v0.5.0.tar.gz
GO111MODULE=on go install -v -mod=vendor -ldflags "-X github.com/lightninglabs/taproot-assets/build.Commit=v0.5.0" ./cmd/tapd
GO111MODULE=on go install -v -mod=vendor -ldflags "-X github.com/lightninglabs/taproot-assets/build.Commit=v0.5.0" ./cmd/tapcli

The -mod=vendor flag tells the go build command that it doesn't need to fetch the dependencies, and instead, they're all enclosed in the local vendor directory.

Additionally, it's now possible to use the enclosed release.sh script to bundle a release for a specific system like so:

make release sys="linux-arm64 darwin-amd64"

⚡️⚡️⚡️ OK, now to the rest of the release notes! ⚡️⚡️⚡️

Release Notes (auto generated)

What's Changed

Pass 'pkg' argument to flake-unit-race Makefile target by @gijswijs in #1044
makefile+scripts: specify Go version for building release binaries by @ffranr in #1051
Store transfer output proof delivery status by @ffranr in #1035
tapchannel: check for feature bits before opening chans by @Roasbeef in #1041
tapchannel: fix proof courier initialization by @guggero in #1058
tapchannel: use new context for call to unlockLeases by @Roasbeef in #1063
Reattempt proof delivery on node restart by @ffranr in #1055
[custom channels]: add new RPC methods for asset channel specific calls by @guggero in #1048
CI: push coverage file for unit tests by @jharveyb in #1069
Expand VerifyOwnershipProof by @sputn1ck in #1075
chore: fix some function names by @murongshaozong in #1079
rfq: actually set subject asset in QueryRateTick by @guggero in #1076
Spend transaction change outputs even if undelivered proof(s) by @ffranr in #1074
rpc: add ChainHash message with both bytes and string representations by @ffranr in #1087
tapdb: fix multiple issues around migration file handling by @guggero in #1089
linter: copy over Go version check scripts from LND by @ffranr in #1080
multi: specify proof courier proof recipient at delivery or receive by @ffranr in #1088
TLV encoding: add forward-compatibility by @guggero in #1037
Add challenge to proof ownership flows by @GeorgeTsagk in #1077
Enhance Proof Courier Handlers with Lazy Connection Attempts for HashMail and UniverseRPC by @ffranr in #1092
[universe]: fix proof sync for large asset minting batches by @guggero in #1093
commitment: splits shouldn't inherit locktime from inputs by @Roasbeef in #1103
Accept price deviation ppm configuration by @lukegao209 in #1109
Server logging cleanup by @ffranr in #1110
Enhance Proof Delivery Resilience with ParSliceErrCollect in ChainPorter by @ffranr in #1100
Add more prometheus metrics by @GeorgeTsagk in #1054
github: run LiT itests & unit tests as part of CI by @ellemouton in #1112
Loadtesting metrics, updated by @GeorgeTsagk in #737
Small fixes after recent PRs by @guggero in #1116
[wallet]: only select BIP-86 script keys for channel funding, add flag to FundVirtualPsbt by @guggero in #1115
tapchannel: improve aux signer signal handling by @jharveyb in #1118
README+docs: create document explaining decimal display and RFQ, add reference implementation by @guggero in #1059
fn+proof: use GOMAXPROCS for worker pool size by @jharveyb in #1123
RFQ cleanup by @ffranr in #1124
tapdb: improve batch marshalling by @jharveyb in #1127
ci: run only custom_channels LiT itests by @ffranr in #1129
Tap channels liquidity fixes by @GeorgeTsagk in #1120
RFQ session lookup during quote accept message parsing by @ffranr in #1128
Add 'include_leased' flag to ListBalances by @gijswijs in #1119
rfqmath: clarify scale requirement in FixedPoint Mul and Div docs by @ffranr in #1137
Add fixed-point WithinTolerance method and greater-than operators by @ffranr in #1135
Align RFQ reject message with BLIP by @ffranr in #1131
Startup related fixes by @GeorgeTsagk in #1126
examples: add TLS support to basic price oracle service by @ffranr in #1140
tapchannel: relax timing for quit and cancel tests by @jharveyb in #1147
Part 1: RFQ uses fixed-points by @ffranr in #1136
rfqmath: simplify price oracle rate example by @ffranr in #1153
tapd: fix L1 assets balance calculation by @gijswijs in #1151
Part 2: RFQ uses fixed-points by @ffranr in #1141
Merge feature-branch RFQ fixedpoint commits into main by @ffranr in #1155
Remove remaining instances of "rate tick" from RFQ systems by @ffranr in #1156
[custom channels]: update to unmerged release branch of lnd 0.18.4-beta by @guggero in #1130
scripts: add missing Go version arg to release.sh usage doc by @ffranr in #1158
Ensure that asset rate hint expiry timestamps are passed to price oracle by @ffranr in #1160
tapchannel: enforce strict forwarding for asset invoices by @GeorgeTsagk in #1144
min_relay_fee check during channel funding by @gijswijs in #1163
rfqmsg: request fields blip align by @ffranr in #1157
Refactor RFQ BuyOrder struct by @ffranr in #1175
Hashmail logging cleanup by @ffranr in #1176
rpc: add asset hodl invoice support by @Roasbeef in #1184
scripts: use trap to make sure old files always restored by @Roasbeef in #1187
tapcfg: allow to configure lnd RPC timeout, increase default val by @guggero in #1177
tapdb: fix bug w.r.t null bool handling, allow InsertScriptKey to allow flipping known to true by @Roasbeef in #1185
tappsbt: add AltLeaf support to vPacket by @jharveyb in #1180
Fix LitD itest CI by @GeorgeTsagk in #1193
tapcfg: add flag to disable default federation server by @guggero in #1190
rfq: fix precision issue in HTLC compliance check by @guggero in #1194
proof: add code for stitching together failed proof suffixes by @guggero in #1188
More RFQ improvments by @ffranr in #1197
[multiverse RPC]: add better universe root node cache by @guggero in #1169
Limit number of HTLCs in custom channel by @guggero in #1132
[tapsend]: Enforce unique script keys by @guggero in #1181
Fee bumping when fee estimation doesn't meet min relay fee by @gijswijs in #1191
[rfq]: add validation to AddAssetBuyOrder and AddAssetSellOrder RPCs by @guggero in #1192
tapchannel: add awareness of 1st and 2nd level HTLC sweeps to the AuxSweeper by @Roasbeef in #1154
tapdb: Add Universe indices, optimize SQL queries, RWMutex for cache by @jbrill in #1174
Add ListBurns RPC by @GeorgeTsagk in #1178
[wallet]: fix signing interaction with lnd, allowing restore from seed by @guggero in #1213
tchrpc: change FundChannel endpoint to POST by @GeorgeTsagk in #1220
[custom channels]: generate unique script keys for HTLCs by @guggero in #1209
version: bump to version v0.5.0-alpha.rc1 by @guggero in #1221
multi: roll back change in request page size by @guggero in #1225
scripts/keys: add roasbeef's new key by @Roasbeef in #1229
rfq: fix potential nil pointer panic by @guggero in #1232
Support user-generated RFQ on tchrpc.SendPayment by @GeorgeTsagk in #1224
mod: bump aperture version to v0.3.4-beta by @guggero in #1223
rpc: try to catch EOF error from lnd sendpayment by @Roasbeef in #1217
Refactor GroupKeyReveal for multi-version support by @ffranr in #1235
Track HTLCs in rfq policies by @GeorgeTsagk in #1186
[custom channels]: add decimal display to channel funding blob by @guggero in #1245
[custom channels]: Fix bandwidth manager and other bugs by @guggero in #1236
Update release notes template re timestamps by @gijswijs in #1237
mod+version: bump lnd to v0.18.4-beta.rc2, bump version to v0.5.0-alpha.rc2 by @guggero in #1248
scripts: update Roasbeef's key ID in verify-install.sh by @guggero in #1249
Strict forwarding pt.2 by @GeorgeTsagk in #1244
[custom channels]: enforce minimum amounts by @guggero in #1252
tapchannel: send+recv chunks of the input proof to stay under max msg limit by @Roasbeef in #1259
rpc: implement DecodeAssetInvoice by @Roasbeef in #1253
Add GroupKeyReveal V1 by @ffranr in #1246
build(deps): bump the go_modules group across 3 directories with 2 updates by @dependabot in #1261
Add AltLeaf support to tapfreighter by @jharveyb in #1233
asset: change all-zero hash to empty leaf by @guggero in #1263
release: bump lnd to final v0.18.4-beta version, bump tapd version to v0.5.0-alpha by @guggero in #1262

New Contributors

@murongshaozong made their first contribution in #1079
@lukegao209 made their first contribution in #1109
@jbrill made their first contribution in #1174

Full Changelog: v0.4.1...v0.5.0

lightninglabs/taproot-assets v0.5.0 v0.5.0-alpha on GitHub