From 1847c39e8e5a956ace79dbc548f55034b7e668bd Mon Sep 17 00:00:00 2001 From: Severin Buhler Date: Tue, 13 Jun 2023 10:37:12 +0800 Subject: [PATCH 1/2] added anchor links and references section --- LSPS0/common-schemas.md | 51 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/LSPS0/common-schemas.md b/LSPS0/common-schemas.md index ef90d22..a313c36 100644 --- a/LSPS0/common-schemas.md +++ b/LSPS0/common-schemas.md @@ -41,6 +41,9 @@ under this specification. ### Monetary Amounts +###### Link: LSPS0.sat +###### Link: LSPS0.msat + Monetary amounts MUST be expressed in either millisatoshi or satoshi units. @@ -80,6 +83,8 @@ encoded as `"546000"` for an `_msat`-suffixed field, or ### On-chain Feerates +###### Link: LSPS0.onchain_fee_rate + On-chain feerates MUST be expressed in units of millisatoshi per weight unit, or equivalently, satoshi per 1000 weight units (sats/kWU). @@ -93,6 +98,8 @@ For example, the minimum feerate would be encoded as `253`. ### Proportional / Parts-per-million +###### Link: LSPS0.ppm + Proportional numbers (i.e. anything that humans might typically express as a perentage) MUST be expressed in units of parts-per-million. @@ -118,6 +125,8 @@ For example, 0.25% would be encoded as `2500`. ### Short Channel Identifiers (SCID) +###### Link: LSPS0.scid + SCIDs MUST be encoded as a JSON string containing the "human-readable" format of `BBBxTTTxOOO`, as defined in [BOLT7 Definition of `short_channel_id`][]. @@ -139,6 +148,8 @@ encoding, would be written as the JSON string `"539268x845x1"`. ### SECP256K1 Points / Public Keys / Lightning Network Node IDs +###### Link: LSPS0.pubkey + Lightning Network node IDs are SECP256K1 ECC public keys, which are points on the SECP256K1 elliptic curve, as noted in [BOLT8](https://github.com/lightning/bolts/blob/50b7391a6ef5310021c2a6378334e65e04e46876/08-transport.md?plain=1#L5-L6). @@ -172,6 +183,8 @@ as the JSON string ### Lightning Network Connection Strings +###### Link: LSPS0.connection_string + Lightning Network connection strings describe a Lightning Network Node ID and one way to connect to that node. @@ -206,6 +219,8 @@ individually parse and validate each part. ### On-chain Addresses +###### Link: LSPS0.onchain_address + An on-chain address MUST be a SegWit address, from version 0 to any future version. @@ -228,6 +243,8 @@ Readers MAY support other SegWit versions. ### Lightning Network Node Signatures +###### Link: LSPS0.ln_signature + Signatures generated by a particular Lightning Network node, with a particular known node ID, MUST be generated and represented using the [LND `signmessage` #specinatweet][], and encoded as a JSON string @@ -274,6 +291,8 @@ For example, a hypothetical LSPS999 might specify: ### Datetimes +###### Link: LSPS0.datetime + Particular points of time in the modern era (a "datetime") MUST be encoded as a JSON string containing the [ISO 8601][] format `"YYYY-MM-DDThh:mm:ss.uuuZ"`. @@ -283,6 +302,8 @@ These are always in the UTC timezone. ### Binary Blobs (Raw Transactions, PSBTs, Lightning onions, etc.) +###### Link: LSPS0.binary_blob + Binary blobs MUST be encoded as a JSON string containing the Base 64 encoding of the binary blob, as described in [RFC 4648 Section 4][]. @@ -303,3 +324,33 @@ Padding characters `=` MUST be used. > not include the padding `=` characters, despite their > uselessness, as this [tweet](https://twitter.com/fiatjaf/status/1558525040374718465) > laments. + + +## References + +All data types defined here MUST be referenced via the provided anchor link. + +### Example + +The field `min_initial_client_balance_sat` is of data type `LSPS0.sat`. You MUST reference it with an anchor link: + +- `min_initial_client_balance_sat` [][] This field is used to describe the minimal initial channel balance on the client side. + +[]: ./common-schemas.md#link-lsps0sat + +### Convenient Schema +To minimize the characters typed, use the following markdown schema. + +```markdown +- `min_initial_client_balance_sat` [][] This field is used to describe the minimum initial channel balance on the client side. +- `max_initial_client_balance_sat` [][] This field is used to describe the maximum initial channel balance on the client side. +- `onchain_address` [][] On-chain address to pay your fee to. +- `lsp_connection_string` [][] Connection string of the LSP. + +[]: ./common-schemas.md#link-lsps0sat +[]: ./common-schemas.md#link-lsps0onchain_address +[]: ./common-schemas.md#link-lsps0connection_string +``` +`#link-lsps0sat` is the anchor link defined in this doc. It is defined as a h6 header (6 times #). + +`./common-schemas.md` is the relative link to this document and needs to be set individually. From 58ce9e090ddf677cdc95e4fc7dc7f3e19ee4a56c Mon Sep 17 00:00:00 2001 From: Severin Buhler Date: Thu, 15 Jun 2023 10:29:17 +0800 Subject: [PATCH 2/2] added new datatypes txid, output_index, and outpoints --- LSPS0/common-schemas.md | 49 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/LSPS0/common-schemas.md b/LSPS0/common-schemas.md index a313c36..0c9fbda 100644 --- a/LSPS0/common-schemas.md +++ b/LSPS0/common-schemas.md @@ -325,6 +325,55 @@ Padding characters `=` MUST be used. > uselessness, as this [tweet](https://twitter.com/fiatjaf/status/1558525040374718465) > laments. +### Transaction IDs + +###### Link: LSPS0.txid + +Transaction ID without witness data as defined in [BIP0141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#transaction-id). + +It MUST be converted to little-endian to enable searching and MUST be encoded as a 64 character HEX string. + +> **Rationale** We use the little-endian format to let users easily copy-paste the txid to a block explorer. +Example: + +```json +{ + "txid": "F27C97F46ED7281A3EFA7287410082EBA0CD1424D72703A217E435EA840957B0" +} +``` + + + +### Output Index + +###### Link: LSPS0.output_index + +`output_index` is the 0 based index for transaction output UTXOs. It is a maximum of [16 bits (2 bytes)](https://github.com/lightning/bolts/blob/aad959a297ff66946effb165518143be15777dd6/07-routing-gossip.md#definition-of-short_channel_id). It MUST be represented as a JSON integer (number). + +Example: + +```json +{ + "output_index": 0 +} +``` + + +### Outpoints + +###### Link: LSPS0.outpoint + +An outpoint consist of a `LSPS0.txid` and a `LSPS0.output_index`. It is defined in [BOLT0](https://github.com/lightning/bolts/blob/master/00-introduction.md#outpoint). It MUST be encoded as a JSON string in the `txid:output_index` format. + +> **Rationale** The `txid:outpoint` format is conveniently used in block explorers and can just be copy pasted to search for the affected UTXO. +Example: + +```json +{ + "funding_outpoint": "F27C97F46ED7281A3EFA7287410082EBA0CD1424D72703A217E435EA840957B0:0" +} +``` + ## References