GITBOOK-373: Leo's Oct 13 changes

lightning-network-tools/taproot-assets/collectibles.md

@@ -6,4 +6,28 @@ description: >-
 
 # Collectibles
 
-In addition to fungible, "normal" assets, Taproot Assets supports the creation and transfer of collectible assets. 
+In addition to fungible, "normal" assets, Taproot Assets supports the creation and transfer of collectible, non-fungible assets.
+
+A digital collectible can take on any form. The collectible itself may be referenced in the form of a hash or text, or may be directly embedded in the meta data itself. When minting a collectible, you have the option to pass any kind of data via `--meta_bytes`, such as text, images encoded data of any form or even a binary blob. Alternatively, any file can be passed to tapd with the `--meta_file_path` flag.
+
+Meta data is limited to 1MB per asset.
+
+Example:
+
+`tapcli assets mint --type collectible --name theone --meta_bytes "One of a kind" --supply 1`
+
+`tapcli assets mint finalize`
+
+## Collections
+
+Multiple collectibles can be grouped together into a collection. Each asset has its own asset ID, while the collection itself can be identified by its group key. To create such a collection, the `--enable_emission` flag has to be set, and each subsequent collectible has to reference the first collectible by its name. Multiple collectibles can be minted in a batch.
+
+`tapcli assets mint --type collectible --name member001 --meta_bytes 546170726f6f742041737365747320436c7562204d656d62657220303031 --supply 1 --enable_emission --group_anchor member001`
+
+`tapcli assets mint --type collectible --name member002 --meta_bytes 546170726f6f742041737365747320436c7562204d656d62657220303032 --supply 1 --enable_emission --group_anchor member001`
+
+`tapcli assets mint --type collectible --name member003 --meta_bytes 546170726f6f742041737365747320436c7562204d656d62657220303033 --supply 1 --enable_emission --group_anchor member001`
+
+`tapcli assets mint finalize`
+
+At this point there is no option to "close" a batch or limit future emissions of that group.

lightning-network-tools/taproot-assets/first-steps.md

@@ -8,7 +8,7 @@ description: >-
 
 ## Minting assets <a href="#docs-internal-guid-3eb3e547-7fff-da1b-7a6b-6865cc97ba7e" id="docs-internal-guid-3eb3e547-7fff-da1b-7a6b-6865cc97ba7e"></a>
 
-Use `tapcli` to begin minting your first asset.
+Use `tapcli` to begin minting your first asset. We are minting a normal, fungible asset and we'll allow ourselves to increase the supply of this asset in the future by setting the `--enable_emission` flag.
 
 `tapcli assets mint --type normal --name beefbux --supply 100 --meta_bytes` 66616e746173746963206d6f6e6579 `--enable_emission`
 
@@ -104,7 +104,9 @@ The output of this command can be explained as follows:
 
 
 
-Assets that were minted with the flag `--emission_true` do not have a fixed supply. A new batch of this asset can be minted later in a way that the two assets are considered of the same asset group, and therefore fungible.
+Assets that were minted with the flag `--enable_emission` do not have a fixed supply. A new batch of this asset can be minted later in a way that the two assets are considered of the same asset group, and therefore fungible.
+
+**Note: At the moment it is not possible to spend two assets with different asset IDs, even if they belong to the same asset group.**
 
 To increase the supply of such an asset, we will need its `tweaked_group_key`.
 
@@ -175,9 +177,9 @@ To send assets, you will need the recipient’s Taproot Assets address. This Tap
 
 When generating a Taproot Assets address, the receiver will create their expected Merkle trees, and tweak a Taproot key with it. The resulting key is converted to a Taproot address, where the receiver waits for an incoming transaction.
 
-To generate a Taproot Assets address requesting 21 beefbux, use the following command:
+To generate a Taproot Assets address requesting 21 beefbux, use the following command from the tapd instance of the receiver:
 
-`tapcli2 addrs new --asset_id 6ab81f9b6b72138bc77189ea4afeabcfdb8722d1d5485ddbefc7a344bd9884e6 --amt 21`
+`tapcli addrs new --asset_id 6ab81f9b6b72138bc77189ea4afeabcfdb8722d1d5485ddbefc7a344bd9884e6 --amt 21`
 
 
 
@@ -214,7 +216,7 @@ You’ll also be able to inspect this address again anytime with the command `ta
 
 ## Sending an asset <a href="#docs-internal-guid-5d8fd7ee-7fff-475c-a392-4855bf9afc85" id="docs-internal-guid-5d8fd7ee-7fff-475c-a392-4855bf9afc85"></a>
 
-To send the asset, run the command below. The sender will then generate the appropriate Merkle trees for the recipient and their change outputs, sign the Taproot Assets transaction with their internal Taproot Assets key and publish the Bitcoin transaction.
+To send the asset, run the command below from a the tapd instance of the sender. This will generate the appropriate Merkle trees for the recipient and their change outputs, sign the Taproot Assets transaction with their internal Taproot Assets key and publish the Bitcoin transaction.
 
 `tapcli assets send --addr taptb1qqqsqqspqqzzq64cr7dkkusn30rhrz02ftl2hn7msu3dr42gthd7l3argj7e3p8xq5ssyecuwudrsw354jxpsuhhzv36w3wm9tv8zu2epa8d66p9drj98canqcssyksqefuaf788ch95089vqnsn8zx5q5sevsv6u9spk0wmzh30elkspqss8ngqlx2t9x96yffvy3wqekzhaewx3ml4k37yvg3s9vgdg069pgwxpgq32rpww4hxjan9wfek2unsvvaz7tm4de5hvetjwdjjumrfva58gmnfdenjuenfdeskucm98gcnqvpj8y3rh965`
 
@@ -286,6 +288,26 @@ By default, this mailbox is set to your default universe, but you can [run your
 
 Once the transaction is confirmed on the Bitcoin Blockchain the sender will attempt to make the proofs available to the recipient via a [LNC-style end-to-end encrypted mailbox](../lightning-terminal/lightning-node-connect.md).
 
+## Burning Assets
+
+Burning assets works by sending assets to a provably unspendable address.&#x20;
+
+`tapcli assets burn --asset_id 9cfada48cd7df34e61c4a29230aaf9f37e44b5381639d7bed667cd2e60565392 --amount 50`
+
+
+
+```
+Please confirm destructive action.
+Asset ID: 9cfada48cd7df34e61c4a29230aaf9f37e44b5381639d7bed667cd2e60565392
+Current available balance: 100
+Amount to burn: 50
+Are you sure you want to irreversibly burn (destroy, remove from circulation)
+ the specified amount of assets?
+Please answer 'yes' or 'no' and press enter: yes
+```
+
+
+
 ## Start building on Taproot Assets
 
 You can find the [API references for `tapd` here](https://lightning.engineering/api-docs/api/taproot-assets).

lightning-network-tools/taproot-assets/get-tapd.md

@@ -35,16 +35,16 @@ Within the `tapd.conf` file you can permanently set your variables, such as dire
 
 Run Taproot Assets with the command `tapd`. Specify how Taproot Assets can reach LND and what bitcoin network to run Taproot Assets with by passing it additional flags.
 
-`tapd --network=testnet --debuglevel=debug --lnd.host=localhost:10009 --lnd.macaroonpath=/.lnd/data/chain/bitcoin/testnet/admin.macaroon --lnd.tlspath=/.lnd/tls.cert --tapdir=~/.taprooot-assets --rpclisten=127.0.0.1:10029 --restlisten=127.0.0.1:8089`
+`tapd --network=testnet --debuglevel=debug --lnd.host=localhost:10009 --lnd.macaroonpath=/.lnd/data/chain/bitcoin/testnet/admin.macaroon --lnd.tlspath=/.lnd/tls.cert --tapddir=~/.tapd --rpclisten=127.0.0.1:10029 --restlisten=127.0.0.1:8089`
 
 You may run multiple tapd instances on the same machine, but you will also have to set up multiple LND instances. [Refer to this guide](../lnd/run-lnd.md) for how to set up multiple LND instances with a single Bitcoin backend using `rpcpolling`. When running multiple `tapd` instances on one machine, don’t forget to set an alternate Taproot Assets directory and API endpoints and specify these when calling `tapcli` as well.
 
 For example, to run a second instance of `tapd`:
 
-`tapd --tapdir=~/.tapd-2 --rpclisten=127.0.0.1:10030 --restlisten=127.0.0.1:8090`
+`tapd --tapddir=~/.tapd-2 --rpclisten=127.0.0.1:10030 --restlisten=127.0.0.1:8090`
 
 To interact with this second instance using `tapcli`:
 
-`tapcli --rpcserver=127.0.0.1:10030 --tapdir=~/.tapd-2`
+`tapcli --rpcserver=127.0.0.1:10030 --tapddir=~/.tapd-2`
 
 You can make use of `tapcli profiles` to make calls to separate `tapd` instances on the same machine.

lightning-network-tools/taproot-assets/operational-safety-guidelines.md

@@ -8,21 +8,21 @@ As of version `v0.3.0-alpha`, Taproot Assets can be used on Bitcoin's `mainnet`
 
 **That means, special care must be taken to avoid loss of funds (both assets and BTC)!**
 
-### [How to avoid loss of funds (short version, tl;dr)](https://github.com/lightninglabs/taproot-assets/blob/193c3ad52bc8e3bde3129dce1d99546606c97c81/docs/safety.md#how-to-avoid-loss-of-funds-short-version-tldr) <a href="#user-content-how-to-avoid-loss-of-funds-short-version-tldr" id="user-content-how-to-avoid-loss-of-funds-short-version-tldr"></a>
+### How to avoid loss of funds (short version, tl;dr) <a href="#user-content-how-to-avoid-loss-of-funds-short-version-tldr" id="user-content-how-to-avoid-loss-of-funds-short-version-tldr"></a>
 
 In short, there is no recovery mechanism in place yet that allows you to recover assets from only the `lnd` seed. So if you lose your `tapd`'s database, or it gets corrupted, you lose access to all assets minted or received by that `tapd`. In addition, you also cannot spend the BTC used to carry/anchor the assets.
 
 **To avoid loss of funds, make sure you back up your `/home/<user>/.tapd` folder regularly.** If you are using a Postgres database as the database backend, it is enough to make backups of that database.
 
 And of course, you also need `lnd`'s seed phrase which is what all private keys for all assets in a `tapd` instance are derived from.
 
-### [How to avoid loss of funds (extended version)](https://github.com/lightninglabs/taproot-assets/blob/193c3ad52bc8e3bde3129dce1d99546606c97c81/docs/safety.md#how-to-avoid-loss-of-funds-extended-version) <a href="#user-content-how-to-avoid-loss-of-funds-extended-version" id="user-content-how-to-avoid-loss-of-funds-extended-version"></a>
+### How to avoid loss of funds (extended version) <a href="#user-content-how-to-avoid-loss-of-funds-extended-version" id="user-content-how-to-avoid-loss-of-funds-extended-version"></a>
 
 Because the Taproot Assets Protocol is an overlay or off-chain protocol, all data relevant to asset mints, transfers or burns are not stored in the Bitcoin blockchain itself. That means, if access to that data is lost, then the assets cannot be recovered by just using a wallet seed.
 
 So-called Universes (public asset and proof databases) will help with storing and later retrieving that crucial off-chain data, but the mechanisms to query all required data by just using `lnd`'s seed are not yet in place. See [#426](https://github.com/lightninglabs/taproot-assets/issues/426) for more information.
 
-#### [What data do I need to back up](https://github.com/lightninglabs/taproot-assets/blob/193c3ad52bc8e3bde3129dce1d99546606c97c81/docs/safety.md#what-data-do-i-need-to-back-up) <a href="#user-content-what-data-do-i-need-to-back-up" id="user-content-what-data-do-i-need-to-back-up"></a>
+#### What data do I need to back up <a href="#user-content-what-data-do-i-need-to-back-up" id="user-content-what-data-do-i-need-to-back-up"></a>
 
 The following items should be backed up regularly (e.g. hourly or even more frequently depending on the number of users/transactions of a system):
 
@@ -37,7 +37,7 @@ The following items should be backed up regularly (e.g. hourly or even more freq
 
 Optionally the copies of the proof files in `<tapddir>/data/<network>/proofs` can be backed up as well, but those are also all contained in the SQLite or Postgres database and are only on the filesystem for faster access.
 
-#### [Where are the private keys for assets stored?](https://github.com/lightninglabs/taproot-assets/blob/193c3ad52bc8e3bde3129dce1d99546606c97c81/docs/safety.md#where-are-the-private-keys-for-assets-stored) <a href="#user-content-where-are-the-private-keys-for-assets-stored" id="user-content-where-are-the-private-keys-for-assets-stored"></a>
+#### Where are the private keys for assets stored? <a href="#user-content-where-are-the-private-keys-for-assets-stored" id="user-content-where-are-the-private-keys-for-assets-stored"></a>
 
 The `tapd` database does not store any private key material. It exclusively uses `lnd`'s wallet to derive keys for assets and their BTC anchoring transactions. The `tapd` database only stores the public key and derivation information in its database.
 
@@ -46,11 +46,11 @@ The following cryptographic keys are derived from `lnd`'s wallet:
 * `internal_key`: The internal keys for BTC-level anchoring transaction outputs that carry asset commitments.
 * `script_key`: The raw key for asset ownership keys, by default used as BIP-0086 keys in the asset output.
 
-#### [Is it safe to restore from an outdated database backup?](https://github.com/lightninglabs/taproot-assets/blob/193c3ad52bc8e3bde3129dce1d99546606c97c81/docs/safety.md#is-it-safe-to-restore-from-an-outdated-database-backup) <a href="#user-content-is-it-safe-to-restore-from-an-outdated-database-backup" id="user-content-is-it-safe-to-restore-from-an-outdated-database-backup"></a>
+#### Is it safe to restore from an outdated database backup? <a href="#user-content-is-it-safe-to-restore-from-an-outdated-database-backup" id="user-content-is-it-safe-to-restore-from-an-outdated-database-backup"></a>
 
 Yes. Since there is no penalty mechanism involved as in Lightning, there is no additional risk when restoring an outdated database backup. But of course, if the database backup is out of date, it might not contain the latest assets and access to those could still be lost.
 
-#### [Is it safe to open the `tapd` RPC port to the internet?](https://github.com/lightninglabs/taproot-assets/blob/193c3ad52bc8e3bde3129dce1d99546606c97c81/docs/safety.md#is-it-safe-to-open-the-tapd-rpc-port-to-the-internet) <a href="#user-content-is-it-safe-to-open-the-tapd-rpc-port-to-the-internet" id="user-content-is-it-safe-to-open-the-tapd-rpc-port-to-the-internet"></a>
+#### Is it safe to open the `tapd` RPC port to the internet? <a href="#user-content-is-it-safe-to-open-the-tapd-rpc-port-to-the-internet" id="user-content-is-it-safe-to-open-the-tapd-rpc-port-to-the-internet"></a>
 
 There is normally no need to open the `tapd` RPC port (10029 by default) to the internet. Unless the intention is to run a public Universe server, then that is the port to expose. By default, all RPC methods (except for some non-sensitive Universe related calls) are protected by macaroon credentials.
 
@@ -60,6 +60,6 @@ There are three flags/config options that should be evaluated though:
 * `--allow-public-stats`: If set, then access to Universe statistics RPC calls are allowed without the requirement for a macaroon. This can be useful to directly pull statistics over the REST interface into any website.
 * `--universe.public-access`: If set, then proofs can be inserted and synced by other nodes. The difference between this flag and `--allow-public-uni-proof-courier` is that the first controls whether remote proofs should be allowed in general, while the second controls whether one needs an authentication token to do so.
 
-### [Important note for Umbrel/Lightning Terminal users](https://github.com/lightninglabs/taproot-assets/blob/193c3ad52bc8e3bde3129dce1d99546606c97c81/docs/safety.md#important-note-for-umbrellightning-terminal-users) <a href="#user-content-important-note-for-umbrellightning-terminal-users" id="user-content-important-note-for-umbrellightning-terminal-users"></a>
+### Important note for Umbrel/Lightning Terminal users <a href="#user-content-important-note-for-umbrellightning-terminal-users" id="user-content-important-note-for-umbrellightning-terminal-users"></a>
 
 If you are using Taproot Assets as part of the "Lightning Terminal" app inside Umbrel (or any comparable node-in-a-box solution), **DO NOT UNDER ANY CIRCUMSTANCE** uninstall (or re-install) the "Lightning Terminal" app without first making a manual backup of all local data of `tapd`. Uninstalling any app on Umbrel will delete that app's data. And in case of Taproot Assets, that data contains information needed to spend both the Taproot Assets **AND** the bitcoin that carry the assets. Just having the `lnd` seed phrase is **NOT** enough to restore assets minted or received.

lightning-network-tools/taproot-assets/universes.md

@@ -1,5 +1,5 @@
 ---
-description: Learn how to run a universe
+description: Learn how to run a universe and connect to other universes.
 ---
 
 # Universes
@@ -14,3 +14,13 @@ Sample`tapd.conf` file:
 `allow-public-uni-proof-courier=true`\
 `allow-public-stats=true universe.public-access=true`
 
+## The default universe
+
+By default, your `tapd` will connect to the default universe, for instance `testnet.universe.lightning.finance:10029` for testnet, or `universe.lightning.finance:10029` on mainnet.
+
+You can add and remove universes from your local federation with `tapcli universe federation add` or `del`.
+
+The contents of the default universe are also available via a public API:
+
+[https://universe.lightning.finance/v1/taproot-assets/universe/roots](https://universe.lightning.finance/v1/taproot-assets/universe/roots)
+