Merge pull request #5 from uma-universal-money-address/feat/markdownlint

Add markdownlint and CI job to check it

.github/workflows/lint.yaml

@@ -0,0 +1,17 @@
+name: "Markdown Lint"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: DavidAnson/markdownlint-cli2-action@v13
+        with:
+          config: ".markdownlint.json"
+          globs: "**/*.md"

.markdownlint.json

@@ -0,0 +1,9 @@
+{
+    "default": true,
+    "MD013": {
+        "line_length": 120,
+        "code_blocks": false,
+        "tables": false,
+        "headers": false
+    }
+}

README.md

@@ -1,6 +1,8 @@
 # UMA Protocol Spec
 
-This is the source of truth protocol definition for UMA. All proposed spec changes should be sent as PRs to this repo. Note that UMA is an extension of LNURL. If your proposal is also applicable to LNURL, the preference should be to [propose a new LUD](https://github.com/lnurl/luds).
+This is the source of truth protocol definition for UMA. All proposed spec changes should be sent as PRs to this repo.
+Note that UMA is an extension of LNURL. If your proposal is also applicable to LNURL, the preference should be to
+[propose a new LUD](https://github.com/lnurl/luds).
 
 This repo is organized as a set of individual documents describing a single message or component of the protocol.
 

umad-01-addresses.md

@@ -1,6 +1,9 @@
 # UMAD-01: UMA Addresses
 
-The UMA address format is based on Lightning Addresses ([LUD-16](https://github.com/lnurl/luds/blob/luds/16.md)), and are themselves valid LNURL Lightning Addresses. They are in the format _$\<username>@\<domainname>_ (eg. _$[email protected]_). Similar to Lightning Addresses ([LUD-16](https://github.com/lnurl/luds/blob/luds/16.md)), the domain will be used to make the first lnurlp call to somevasp.com.
+The UMA address format is based on Lightning Addresses ([LUD-16](https://github.com/lnurl/luds/blob/luds/16.md)), and
+are themselves valid LNURL Lightning Addresses. They are in the format _$\<username>@\<domainname>_
+(eg. _$[email protected]_). Similar to Lightning Addresses ([LUD-16](https://github.com/lnurl/luds/blob/luds/16.md)),
+the domain will be used to make the first lnurlp call to somevasp.com.
 
 ![UMA Address Diagram](/images/address_diagram.png)
 
@@ -9,6 +12,7 @@ The UMA address format is based on Lightning Addresses ([LUD-16](https://github.
 - Must start with a $ symbol. This is to differentiate from email addresses and clearly identify an uma address.
 - The \<username> portion is limited to `a-z0-9-_.+`
 - Addresses are case-insensitive, but by convention are written only with lowercase letters
-- Like email addresses, the maximum number of characters for the \<username> portion of the address is 64 characters (including the $).
+- Like email addresses, the maximum number of characters for the \<username> portion of the address is 64 characters
+(including the $).
 
 The UMA SDKs validate these requirements and will throw an error if they are not met.

umad-02-keys-and-authentication.md

@@ -2,9 +2,12 @@
 
 ## Keys
 
-Before VASPs start sending and receiving UMA payments, they need to generate keys which are be used to authenticate themselves to other VASPs and to receive and decrypt encrypted blobs for sensitive information (like payment and Travel Rule data).
+Before VASPs start sending and receiving UMA payments, they need to generate keys which are be used to authenticate
+themselves to other VASPs and to receive and decrypt encrypted blobs for sensitive information (like payment and Travel
+Rule data).
 
-**The keys used in UMA are secp256k1 keys**. They are used to sign, verify, encrypt, and decrypt messages. As an example, to create secp256k1 keys using openssl, run:
+**The keys used in UMA are secp256k1 keys**. They are used to sign, verify, encrypt, and decrypt messages. As an example,
+to create secp256k1 keys using openssl, run:
 
 ```bash
 # Generate a secp256k1 key:
@@ -14,11 +17,16 @@ $ openssl ecparam -genkey -name secp256k1 -out ec_key.pem -param_enc explicit
 $ openssl ec -in ec_key.pem -noout -text
 ```
 
-There are two secp256k1 key pairs used in the UMA protocol, the signing key and encryption key. The signing key is used for signing messages sent to other VASPs and for verifying that other VASPs are who they claim to be. The encryption key is used to encrypt sensitive data sent to you, like payment and Travel Rule information. Note that in practice, these can actually be the same key for convenience. Keys can also be configured to expire as described in the following section.
+There are two secp256k1 key pairs used in the UMA protocol, the signing key and encryption key. The signing key is used
+for signing messages sent to other VASPs and for verifying that other VASPs are who they claim to be. The encryption
+key is used to encrypt sensitive data sent to you, like payment and Travel Rule information. Note that in practice,
+these can actually be the same key for convenience. Keys can also be configured to expire as described in the following
+section.
 
 ## Public Key Exchange
 
-VASPs expose their public keys to other VASPs by responding to `GET` requests at the endpoint `https://<vaspdomain>/.well-known/lnurlpubkey`. This endpoint returns a JSON object with the following structure:
+VASPs expose their public keys to other VASPs by responding to `GET` requests at the endpoint
+`https://<vaspdomain>/.well-known/lnurlpubkey`. This endpoint returns a JSON object with the following structure:
 
 ```json
 {
@@ -32,14 +40,27 @@ VASPs expose their public keys to other VASPs by responding to `GET` requests at
 }
 ```
 
-VASPs can also use this endpoint to refresh their keys by returning a new set of keys with a new expiration timestamp. This is useful if a VASP's keys are compromised or if they want to rotate their keys for security reasons. When receiving a new set of keys, VASPs can cache them until the expiration timestamp.
+VASPs can also use this endpoint to refresh their keys by returning a new set of keys with a new expiration timestamp.
+This is useful if a VASP's keys are compromised or if they want to rotate their keys for security reasons. When receiving
+a new set of keys, VASPs can cache them until the expiration timestamp.
 
-Because the `/.well-known/lnurlpubkey` endpoint is hosted directly on the VASP's domain, it is easy for other VASPs to verify that the keys they receive are actually from the VASP they are trying to communicate with. It does, however, imply trust in the VASP's domain and DNS. As an additional security measure, VASPs can also verify the authenticity of the keys they receive by communicating with a **VASP Identity Authority**, a trusted 3rd party who maintains a mapping from VASP domains to public keys. This step is optional and any VASP ID Authority will provide APIs or interfaces separate from UMA.
+Because the `/.well-known/lnurlpubkey` endpoint is hosted directly on the VASP's domain, it is easy for other VASPs to
+verify that the keys they receive are actually from the VASP they are trying to communicate with. It does, however, imply
+trust in the VASP's domain and DNS. As an additional security measure, VASPs can also verify the authenticity of the
+keys they receive by communicating with a **VASP Identity Authority**, a trusted 3rd party who maintains a mapping from
+VASP domains to public keys. This step is optional and any VASP ID Authority will provide APIs or interfaces separate
+from UMA.
 
 ## Authentication
 
-Some messages in the UMA protcol must be signed by the VASP who created the message using ECDSA and the secp256k1 keys as described above. Signatures are created using a VASP's private signing key. The signature is then verified by the receiving VASP using the sending VASP's `signingPubKey`. The signature is included in the message itself, along with the sending VASP's domain if needed. The receiving VASP can then verify the signature using the public key and ensure that the message was not tampered with.
+Some messages in the UMA protcol must be signed by the VASP who created the message using ECDSA and the secp256k1 keys
+as described above. Signatures are created using a VASP's private signing key. The signature is then verified by the
+receiving VASP using the sending VASP's `signingPubKey`. The signature is included in the message itself, along with the
+sending VASP's domain if needed. The receiving VASP can then verify the signature using the public key and ensure that
+the message was not tampered with.
 
 ## Encryption
 
-VASPs encrypt sensitive information like payment and Travel Rule information using the receiving VASP's `encryptionPubKey` via [ECIES](https://cryptobook.nakov.com/asymmetric-key-ciphers/ecies-public-key-encryption). The receiving VASP can then decrypt the data using their private encryption key only when required for compliance reasons.
+VASPs encrypt sensitive information like payment and Travel Rule information using the receiving VASP's `encryptionPubKey`
+via [ECIES](https://cryptobook.nakov.com/asymmetric-key-ciphers/ecies-public-key-encryption). The receiving VASP can
+then decrypt the data using their private encryption key only when required for compliance reasons.

umad-03-lnurlp-request.md

@@ -1,6 +1,8 @@
 # UMAD-03: LNURLP Request
 
-The first request in the UMA protocol is the LNURLP request, which aligns with LNURL-PAY ([LUD-06](https://github.com/lnurl/luds/blob/luds/06.md)), but with a few added query parameters for compliance and authentication.
+The first request in the UMA protocol is the LNURLP request, which aligns with LNURL-PAY
+([LUD-06](https://github.com/lnurl/luds/blob/luds/06.md)), but with a few added query parameters for compliance and
+authentication.
 
 If `[email protected]` is paying `[email protected]`, the request looks like:
 
@@ -9,8 +11,11 @@ GET https://vasp2.com/.well-known/lnurlp/$bob?umaVersion=1.0&nonce=1234&vaspDoma
 ```
 
 - `umaVersion` **(string)**: is the UMA protocol version supported by VASP1. See the [versioning UMAD](/umad-08-versioning.md).
-- `vaspDomain` **(string)**: is the domain name of the sending vasp. This will be used when validating the signature as per [UMAD-02](/umad-02-keys-and-authentication.md).
+- `vaspDomain` **(string)**: is the domain name of the sending vasp. This will be used when validating the signature as
+per [UMAD-02](/umad-02-keys-and-authentication.md).
 - `isSubjectToTravelRule` **(bool)**: indicates vasp1 is a financial institution that is subject to the Travel Rule.
 - `nonce` **(string)**: is a random unique string generated by the SDK that is used to prevent replay attacks.
 - `timestamp` **(long)**: is the unix timestamp in seconds (number of seconds since epoch).
-- `signature` **(string)**: is vasp1's signature over `hash("[email protected]" + nonce + timestamp)`. Signatures are always hex-encoded strings for UMA. Details on signatures, keys, and how to generate them can be found in [UMAD-02: Keys and Authentication](/umad-02-keys-and-authentication.md).
+- `signature` **(string)**: is vasp1's signature over `hash("[email protected]" + nonce + timestamp)`. Signatures are
+always hex-encoded strings for UMA. Details on signatures, keys, and how to generate them can be found in
+[UMAD-02: Keys and Authentication](/umad-02-keys-and-authentication.md).

umad-04-lnurlp-response.md

@@ -1,8 +1,11 @@
 # UMAD-04: LNURLP Response
 
-The response to the LNURLP request is an extension of LNURL's [LUD-06](https://github.com/lnurl/luds/blob/luds/06.md). It also utilizes the payer data spec as described in [LUD-18](https://github.com/lnurl/luds/blob/luds/18.md) and a slightly modified version of the local currency spec proposed in [LUD-21](https://github.com/lnurl/luds/pull/207). The full structure of the LNURLP response is:
+The response to the LNURLP request is an extension of LNURL's [LUD-06](https://github.com/lnurl/luds/blob/luds/06.md).
+It also utilizes the payer data spec as described in [LUD-18](https://github.com/lnurl/luds/blob/luds/18.md) and a
+slightly modified version of the local currency spec proposed in [LUD-21](https://github.com/lnurl/luds/pull/207).
+The full structure of the LNURLP response is:
 
-```
+```raw
 {
   "callback": string,
   // Max millisatoshi amount the receiver is willing to receive.
@@ -52,4 +55,5 @@ The response to the LNURLP request is an extension of LNURL's [LUD-06](https://g
 }
 ```
 
-The signature here is over `sha256_hash(<receiver UMA> (eg. "[email protected]") + nonce + timestamp)`. The receiving VASPs `signingPubKey` can be used by the sending VASP to verify the signature as described in [UMAD-02](/umad-02-keys-and-authentication.md).
+The signature here is over `sha256_hash(<receiver UMA> (eg. "[email protected]") + nonce + timestamp)`.
+The receiving VASPs `signingPubKey` can be used by the sending VASP to verify the signature as described in [UMAD-02](/umad-02-keys-and-authentication.md).

umad-05-payreq-request.md

@@ -1 +1,6 @@
-# UMAD-05: Payreq Request
+# UMAD-05: Payreq Request
+
+The first request in the UMA protocol is the payreq request, which aligns with the same request in LNURL-PAY
+([LUD-06](https://github.com/lnurl/luds/blob/luds/06.md)), but with a few added query parameters for compliance,
+currency conversion, and authentication. This request tells the receiving VASP to generate an invoice for a specified
+amount on behalf of the receiving user.

umad-06-payreq-response.md

@@ -1 +1 @@
-# UMAD-06: Payreq Response
+# UMAD-06: Payreq Response

umad-07-post-tx-hooks.md

@@ -1 +1 @@
-# UMAD-07: Post-transaction compliance hooks
+# UMAD-07: Post-transaction compliance hooks

umad-08-versioning.md

@@ -1 +1 @@
-# UMAD-08 Versioning
+# UMAD-08 Versioning