Skip to content

Commit ce00c85

Browse files
github-actions[bot]github-actions[bot]
authored
Merge pull request #973 from lightninglabs/docs-taproot-assets
Update taproot-assets documentation
2 parents 084be31 + 6504f54 commit ce00c85

File tree

2 files changed

+173
-0
lines changed

2 files changed

+173
-0
lines changed

‎docs/taproot-assets/metadata/stablecoin.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Taproot Assets Stablecoin Metadata Standard
2+
3+
> Version 1
4+
5+
## Summary
6+
7+
This document describes the metadata specification for stablecoins minted on
8+
the [Taproot Assets Protocol](https://docs.lightning.engineering/the-lightning-network/taproot-assets).
9+
When minting assets, issuers can include additional metadata about the asset
10+
which will be stored and synchronized with universes. Specifying the metadata
11+
using this standard allows applications like
12+
[Terminal](https://terminal.lightning.engineering) to pull in rich data and
13+
display them in the UI. The specification outlined below focuses solely on
14+
stablecoin assets that will not have a fixed supply. It is expected that
15+
there will be multiple issuance and burn events using the same Group Key to
16+
ensure fungibility between asset tranches.
17+
18+
## Motivation
19+
20+
In the Taproot Asset Protocol, every asset has a name defined at the time of
21+
mint. It is common in the digital asset industry for assets to also have
22+
additional information, such as a ticker (acronym), long name, logo image, and
23+
description. The asset `metadata` field is the intended place to store this
24+
kind of information. The Taproot Assets Protocol does not prescribe any
25+
structure to the data stored here other than a 1MB size limit. The goal of
26+
this document is to provide a specification that will allow asset issuers and
27+
app developers to coalesce around a single metadata structure to maximize
28+
compatibility throughout the industry.
29+
30+
## Metadata Structure
31+
32+
The metadata should be a JSON encoded string containing the additional
33+
information about the asset.
34+
35+
### Sample
36+
37+
```json
38+
{
39+
"spec": "stablecoin",
40+
"version": 1,
41+
"ticker": "USDT",
42+
"long_name": "Tether",
43+
"description": "All USDT tokens are pegged at 1-to-1 with a matching fiat currency and are backed 100% by Tether's Reserves. Information about Tether Tokens in circulation is typically published daily.",
44+
"logo_image": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNDgiIGhlaWdodD0iNDgiIHZpZXdCb3g9IjAgMCA0OCA0OCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPGcgaWQ9IkZyYW1lIDUyNjAiPgo8cmVjdCB3aWR0aD0iNDgiIGhlaWdodD0iNDgiIHJ4PSIyNCIgZmlsbD0iIzI2QTE3QiIvPgo8cGF0aCBpZD0iVmVjdG9yIiBkPSJNMjYuNTcwOSAyNS44MThDMjYuNDI4NiAyNS44MTggMjUuODE2NiAyNS44NzYzIDI0LjAyNzcgMjUuODc2M0MyMi41OTM3IDI1Ljg3NjMgMjEuNzgyOSAyNS44MzM0IDIxLjQyOCAyNS44MThDMTUuOTA1NCAyNS41NzI5IDExLjU3NjkgMjQuNjA0MyAxMS41NzY5IDIzLjQzMzRDMTEuNTc2OSAyMi4yNjI2IDE1LjkwNTQgMjEuMjc5NCAyMS40MjggMjEuMDMzNFYyNC44NTAzSDI2LjU3MDlWMjEuMDM0M0MzMi4wNzg5IDIxLjI3OTQgMzYuNDA3NCAyMi4yNjI2IDM2LjQwNzQgMjMuNDMzNEMzNi40MDc0IDI0LjU4OTcgMzIuMDc4OSAyNS41NzI5IDI2LjU3MDkgMjUuODE4Wk0yNi41NzA5IDIwLjYyOTdWMTcuMTQyOUgzNC4yODUyVjEySDEzLjcxMzdWMTcuMTQyOUgyMS40MjhWMjAuNjI4OUMxNS4xODEyIDIwLjkxODYgMTAuMjg1MiAyMi4xOTA2IDEwLjI4NTIgMjMuNjkzMUwxMC4yODUyIDI1LjE5NjYgMTUuMTgxMiAyNi40Njg2IDIxLjQyOCAyNi43NTgzVjM3LjcxNDNIMjYuNTcwOVYyNi43NTgzQzMyLjgxNzcgMjYuNDY4NiAzNy43MTM3IDI1LjE5NjYgMzcuNzEzNyAyMy42OTMxQzM3LjcxMzcgMjIuMTkwNiAzMi44MTc3IDIwLjkzMzEgMjYuNTcwOSAyMC42Mjg5VjIwLjYyOTdaIiBmaWxsPSJ3aGl0ZSIvPgo8L2c+Cjwvc3ZnPgo="
45+
}
46+
```
47+
48+
### Fields
49+
50+
#### `spec`
51+
52+
| Data Type | Values | Required |
53+
| --------- | ------------ | -------- |
54+
| enum | `stablecoin` | True |
55+
56+
A discriminator field that declares the specification used for the metadata.
57+
Having this field allows for other specifications to exist in the future (ex:
58+
fixed supply, collectible, etc.) without introducing potential conflicts in
59+
the field names. When using the standard described in this document, the
60+
value “stablecoin” should always be used.
61+
62+
#### `version`
63+
64+
| Data Type | Required |
65+
| --------- | -------- |
66+
| `number` | True |
67+
68+
Declares the version of the above spec that the content in the metadata
69+
adheres to. The additional fields in each spec may evolve over time. This
70+
field should be used to allow applications to easily determine which fields
71+
are expected to be defined based on the version number.
72+
73+
#### `ticker`
74+
75+
| Data Type | Required |
76+
| --------- | -------- |
77+
| `string` | False |
78+
79+
The ticker symbol commonly used on exchanges and financial platforms to
80+
uniquely identify this asset. (ex: BTC, USDT, USDC). If this field is not
81+
provided, the native TAP asset name should be used in its place.
82+
83+
#### `long_name`
84+
85+
| Data Type | Required |
86+
| --------- | -------- |
87+
| `string` | False |
88+
89+
A more user-friendly name for the asset. (ex: Bitcoin, Tether, USD Coin). If
90+
this field is not provided, the ticker may be used in its place.
91+
92+
#### `description`
93+
94+
| Data Type | Required |
95+
| --------- | -------- |
96+
| `string` | False |
97+
98+
A description of the asset provided by the issuer.
99+
100+
#### `logo_image`
101+
102+
| Data Type | Required |
103+
| ----------------------------------------------------------------------------------------- | -------- |
104+
| [data:image URL](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data) | False |
105+
106+
The URL to use for the logo image. The value must be a
107+
[data:image URL](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data)
108+
which contains the base64 encoded bytes as a string within the content of the
109+
JSON metadata. This ensures the image will persist without reliance on any
110+
third-party hosting. It is recommended to use a square image no larger than
111+
128x128 pixels.
112+
113+
## Minting with Metadata
114+
115+
The simplest way to mint an asset with JSON metadata is to use the
116+
`--meta_file_path` parameter as this eliminates the need to properly escape
117+
the special characters included in the JSON content in the shell or script.
118+
119+
First, create the JSON file containing the fields above with the values
120+
specific to your asset. Then run the `tapcli assets mint` command with the
121+
appropriate arguments.
122+
123+
### Example
124+
125+
```bash
126+
tapcli assets mint --type=normal --name=TEST --supply=100000 --decimal_display=2 --meta_file_path=/path/to/metadata.json --new_grouped_asset
127+
```
128+
129+
### Minting Additional Assets
130+
131+
When minting additional units of the same asset, be sure to include the
132+
metadata each time. If you’d like to update the `long_name`, `description`, or
133+
`logo_image`, you may change those values in subsequent mints. It is
134+
recommended for app developers to use the values from the most recent mint to
135+
display in their apps.
136+
137+
### Decimal Display
138+
139+
When minting assets with the --decimal_display parameter, the value specified
140+
will be merged into the resulting JSON alongside the content you provide. You
141+
should not include this field in your JSON file as it will be overwritten by
142+
the CLI parameter.
143+
144+
If we ran the example command above, when applications decode the metadata it
145+
will look like this:
146+
147+
```json
148+
{
149+
"spec": "stablecoin",
150+
"version": 1,
151+
"ticker": "TEST",
152+
"long_name": "Test Asset",
153+
"description": "Test description of the asset",
154+
"logo_image": "data:image/svg+xml;base64,PHN2Zy...3ZnPgo=",
155+
"decimal_display": 2
156+
}
157+
```
158+
159+
Check out the
160+
[docs](https://github.com/lightninglabs/taproot-assets/blob/main/docs/rfq-and-decimal-display.md)
161+
to learn more about how the decimal display field should be used.
162+
163+
### Viewing Metadata
164+
165+
After minting an asset, you can see the embedded metadata by running the
166+
following CLI command:
167+
168+
```bash
169+
tapcli assets --asset_id <id> | jq -r '.data' | xxd -p -r | jq
170+
```

‎docs/taproot-assets/release-notes/release-notes-0.8.0.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,9 @@
6363

6464
## Code Health
6565

66+
- [PR#1897](https://github.com/lightninglabs/taproot-assets/pull/1897)
67+
Fix witness writeback issue when a split commitment is present.
68+
6669
## Breaking Changes
6770

6871
## Performance Improvements

0 commit comments

Comments
 (0)