From 5890e8513cfbb9798ecf311ae71e4c08ecb20dda Mon Sep 17 00:00:00 2001
From: "David A. Harding" <dave@dtrt.org>
Date: Fri, 12 Jan 2024 13:43:28 -1000
Subject: [PATCH] Topics: add several new topic pages

---
 _data/schemas/topics.yaml                     |  1 +
 _topics/en/annex.md                           | 61 ++++++++++++
 _topics/en/bip70-payment-protocol.md          |  1 +
 _topics/en/bls-signatures.md                  | 81 ++++++++++++++++
 .../en/cross-input-signature-aggregation.md   | 76 +++++++++++++++
 _topics/en/lnurl.md                           | 92 +++++++++++++++++++
 _topics/en/offers.md                          |  2 +
 7 files changed, 314 insertions(+)
 create mode 100644 _topics/en/annex.md
 create mode 100644 _topics/en/bls-signatures.md
 create mode 100644 _topics/en/cross-input-signature-aggregation.md
 create mode 100644 _topics/en/lnurl.md

diff --git a/_data/schemas/topics.yaml b/_data/schemas/topics.yaml
index 16150c53b..fa7c4ebdc 100644
--- a/_data/schemas/topics.yaml
+++ b/_data/schemas/topics.yaml
@@ -30,6 +30,7 @@ properties:
         - Contract Protocols
         - Developer Tools
         - Fee Management
+        - Invoicing
         - Lightning Network
         - Lightweight Client Support
         - Liquidity Management
diff --git a/_topics/en/annex.md b/_topics/en/annex.md
new file mode 100644
index 000000000..a2a068701
--- /dev/null
+++ b/_topics/en/annex.md
@@ -0,0 +1,61 @@
+---
+title: Annex
+
+## Optional.  Shorter name to use for reference style links e.g., "foo"
+## will allow using the link [topic foo][].  Not case sensitive
+# shortname: foo
+
+## Optional.  An entry will be added to the topics index for each alias
+#aliases:
+#  - Foo
+
+## Required.  At least one category to which this topic belongs.  See
+## schema for options
+categories:
+  - Scripts and Addresses
+
+## Optional.  Produces a Markdown link with either "[title][]" or
+## "[title](link)"
+primary_sources:
+    - title: "BIP341: Taproot"
+      link: bip341
+
+## Optional.  Each entry requires "title" and "url".  May also use "feature:
+## true" to bold entry and "date"
+optech_mentions:
+  - title: "Bitcoin Inquisition #22 adds an `-annexcarrier` runtime option"
+    url: /en/newsletters/2023/03/29/#bitcoin-inquisition-22
+
+  - title: Discussion about the taproot annex
+    url: /en/newsletters/2023/06/14/#discussion-about-the-taproot-annex
+
+  - title: Suggestion to store fee-dependent timelock parameters in the taproot annex
+    url: /en/newsletters/2024/01/03/#fee-dependent-timelocks
+
+## Optional.  Same format as "primary_sources" above
+see_also:
+  - title: Taproot
+    link: topic taproot
+
+## Optional.  Force the display (true) or non-display (false) of stub
+## topic notice.  Default is to display if the page.content is below a
+## threshold word count
+#stub: false
+
+## Required.  Use Markdown formatting.  Only one paragraph.  No links allowed.
+## Should be less than 500 characters
+excerpt: >
+  The taproot **annex** is an optional field in the witness structure of
+  segwit v1 (taproot) inputs that currently has no defined purpose.
+  If an annex is present, any taproot and tapscript signatures must
+  commit to its value.
+
+---
+As of the implementation and activation of taproot, the annex was
+reserved for future upgrades.  Transactions containing an annex were not
+relayed or mined by default by Bitcoin Core.  There have been several
+ideas for using the annex, as well as at least one attempt to define an
+extensible data structure for the field.
+
+{% include references.md %}
+{% include linkers/issues.md issues="" %}
diff --git a/_topics/en/bip70-payment-protocol.md b/_topics/en/bip70-payment-protocol.md
index 39b085108..5761ea046 100644
--- a/_topics/en/bip70-payment-protocol.md
+++ b/_topics/en/bip70-payment-protocol.md
@@ -9,6 +9,7 @@ title: BIP70 payment protocol
 ## schema for options
 categories:
   - Wallet Collaboration Tools
+  - Invoicing
 
 ## Required.  Use Markdown formatting.  Only one paragraph.  No links allowed.
 ## Should be less than 500 characters
diff --git a/_topics/en/bls-signatures.md b/_topics/en/bls-signatures.md
new file mode 100644
index 000000000..ab22079fd
--- /dev/null
+++ b/_topics/en/bls-signatures.md
@@ -0,0 +1,81 @@
+---
+title: BLS signatures
+
+## Optional.  Shorter name to use for reference style links e.g., "foo"
+## will allow using the link [topic foo][].  Not case sensitive
+# shortname: foo
+
+## Optional.  An entry will be added to the topics index for each alias
+#aliases:
+#  - Foo
+
+## Required.  At least one category to which this topic belongs.  See
+## schema for options
+categories:
+  - Scripts and Addresses
+
+## Optional.  Produces a Markdown link with either "[title][]" or
+## "[title](link)"
+#primary_sources:
+#    - title: Test
+#    - title: Example
+#      link: https://example.com
+
+## Optional.  Each entry requires "title" and "url".  May also use "feature:
+## true" to bold entry and "date"
+optech_mentions:
+  - title: Library announced for BLS signatures
+    url: /en/newsletters/2018/08/07/#library-announced-for-bls-signatures
+
+  - title: "Presentation: compact multisignatures for smaller blockchains"
+    url: /en/newsletters/2018/10/09/#compact-multi-signatures-for-smaller-blockchains
+
+  - title: "Using Bitcoin-compatible BLS signatures for Discree Log Contracts (DLCs)"
+    url: /en/newsletters/2022/08/17/#using-bitcoin-compatible-bls-signatures-for-dlcs
+
+  - title: "Question about schnorr signatures versus BLS signatures"
+    url: /en/newsletters/2023/01/25/#bls-signatures-vs-schnorr
+
+## Optional.  Same format as "primary_sources" above
+see_also:
+  - title: Scriptless multisignatures
+    link: topic multisignature
+
+## Optional.  Force the display (true) or non-display (false) of stub
+## topic notice.  Default is to display if the page.content is below a
+## threshold word count
+#stub: false
+
+## Required.  Use Markdown formatting.  Only one paragraph.  No links allowed.
+## Should be less than 500 characters
+excerpt: >
+  Boneh--Lynn--Shacham signatures (**BLS signatures**) are digital
+  signatures that provide a different set of tradeoffs compared to the
+  ECDSA and schnorr signatures currently used in Bitcoin.
+---
+Probably the most interesting property of BLS signatures is that they
+allow non-interactive signature aggregation.  For example, if Alice and
+Bob both independently sign the same transaction, a third party can
+combine their signatures into a single signature that proves both of
+them signed.  By comparison, using a Bitcoin's existing [schnorr
+signatures][topic schnorr signatures], a single signature proving both
+of them signed can only be produce through an interactive protocol like
+[MuSig2][topic musig] where at least one of them receives the other's
+partial signature before producing their own partial signature and
+producing the complete signature.
+
+In theory, if other changes to Bitcoin were made and if support for BLS
+signatures was added, miners could aggregate all signatures together
+before producing a block, allowing blocks to contain only a single
+signature, which would moderately improve onchain capacity and might
+speed block verification when cached verification was unavailable (e.g.
+during initial block download).
+
+BLS signatures are not directly compatible with the elliptic curve used
+by Bitcoin and are not as well studied as [schnorr signatures][topic
+schnorr signatures].  It would not be possible to use [signature
+adaptors][topic adaptor signatures] and technology based on them (such
+as [PTLCs][topic ptlc]) with BLS signatures.
+
+{% include references.md %}
+{% include linkers/issues.md issues="" %}
diff --git a/_topics/en/cross-input-signature-aggregation.md b/_topics/en/cross-input-signature-aggregation.md
new file mode 100644
index 000000000..61f5988d3
--- /dev/null
+++ b/_topics/en/cross-input-signature-aggregation.md
@@ -0,0 +1,76 @@
+---
+title: Cross-input signature aggregation (CISA)
+
+## Optional.  Shorter name to use for reference style links e.g., "foo"
+## will allow using the link [topic foo][].  Not case sensitive
+shortname: cisa
+
+## Optional.  An entry will be added to the topics index for each alias
+aliases:
+  - Half aggregation
+
+## Required.  At least one category to which this topic belongs.  See
+## schema for options
+categories:
+  - Scripts and Addresses
+  - Soft Forks
+
+## Optional.  Produces a Markdown link with either "[title][]" or
+## "[title](link)"
+primary_sources:
+    - title: "Cross-input signature aggregation research repository"
+      link: https://github.com/BlockstreamResearch/cross-input-aggregation
+
+## Optional.  Each entry requires "title" and "url".  May also use "feature:
+## true" to bold entry and "date"
+optech_mentions:
+  - title: "Taproot to not include cross-input signature aggregation"
+    url: /en/newsletters/2019/05/14/#no-cross-input-signature-aggregation
+
+  - title: "Question: why does signature aggregation interefer with signature adaptors?"
+    url: /en/newsletters/2021/06/30/#why-does-blockwide-signature-aggregation-prevent-adaptor-signatures
+
+  - title: Draft BIP about half aggregation of BIP340 schnorr signatures
+    url: /en/newsletters/2022/07/13/#half-aggregation-of-bip340-signatures
+
+## Optional.  Same format as "primary_sources" above
+see_also:
+  - title: Schnorr signatures
+    link: topic schnorr signatures
+
+  - title: BLS signatures
+    link: topic bls signatures
+
+## Optional.  Force the display (true) or non-display (false) of stub
+## topic notice.  Default is to display if the page.content is below a
+## threshold word count
+#stub: false
+
+## Required.  Use Markdown formatting.  Only one paragraph.  No links allowed.
+## Should be less than 500 characters
+excerpt: >
+  **Cross-input signature aggregation** is a proposal to reduce the
+  number of signatures a transaction requires.  In theory, every
+  signature required to a make a transaction valid could be combined into a
+  single signature that covers the whole transaction.
+
+---
+For example, Alice controls two [P2TR][topic taproot] UTXOs.  Normally,
+if she creates a transaction spending both UTXOs with a keypath spend,
+she'll need to include one 16-vbyte signature in each output.  However,
+any node could aggregate both public keys from the UTXOs and Alice could
+produce a single 16-vbyte [MuSig]topic musig]-style [scriptless
+multisigature][topic multisignature] that corresponded to the aggregate
+public key, proving that she controlled the private key for both of the
+original public keys.
+
+Although inputs would still need to include a significant amount of
+other data, such as the 36-vbyte outpoint that uniquely identifies the
+UTXO being spent, CISA could provide a modest reduction in the size of
+transactions with multiple inputs.  It could make the per-participant
+transaction fees for a [coinjoin][topic coinjoin] moderately cheaper than each
+participant creating a transaction on their own, which could lead to
+more people using coinjoin-style privacy.
+
+{% include references.md %}
+{% include linkers/issues.md issues="" %}
diff --git a/_topics/en/lnurl.md b/_topics/en/lnurl.md
new file mode 100644
index 000000000..afce63796
--- /dev/null
+++ b/_topics/en/lnurl.md
@@ -0,0 +1,92 @@
+---
+title: LNURL
+
+## Optional.  Shorter name to use for reference style links e.g., "foo"
+## will allow using the link [topic foo][].  Not case sensitive
+# shortname: foo
+
+## Optional.  An entry will be added to the topics index for each alias
+aliases:
+  - Lightning Addresses
+
+## Required.  At least one category to which this topic belongs.  See
+## schema for options
+categories:
+  - Lightning Network
+  - Invoicing
+
+## Optional.  Produces a Markdown link with either "[title][]" or
+## "[title](link)"
+primary_sources:
+    - title: "LNURL Documents (LUDs)"
+      link: https://github.com/lnurl/lud
+
+## Optional.  Each entry requires "title" and "url".  May also use "feature:
+## true" to bold entry and "date"
+optech_mentions:
+  - title: "Discussion about a BIP70 replacement, including a version that works with LNURL"
+    url: /en/newsletters/2021/03/03/#discussion-about-a-bip70-replacement
+
+  - title: "Phoenix v1.4.12 adds support for the LNURL-pay protocol"
+    url: /en/newsletters/2021/06/23/#phoenix-adds-lnurl-pay
+
+  - title: "Stacker News launched with LNURL authentication"
+    url: /en/newsletters/2021/07/21/#lightning-powered-news-site-stacker-news-launches
+
+  - title: "Lightning Address identifiers announced based on LNURL"
+    url: /en/newsletters/2021/09/22/#lightning-address-identifiers-announced
+
+  - title: "BTCPay Server #3083 allows administrators to log in using LNURL authentication"
+    url: /en/newsletters/2022/01/26/#btcpay-server-3083
+
+  - title: "C-Lightning #5121 updates its `invoice` RPC for improved LNURL compatibility"
+    url: /en/newsletters/2022/04/06/#c-lightning-5121
+
+  - title: Large size of blinded paths may make them dependent on invoice protocols like LNURL or offers
+    url: /en/newsletters/2022/06/15/#blinded-paths
+
+  - title: Dicussion about how to make LNURL and offers compatible
+    url: /en/newsletters/2022/06/15/#lnurl-plus-bolt12
+
+  - title: "BTCPay Server #3709 adds support for pull payments to be received via a LNURL withdraw"
+    url: /en/newsletters/2022/07/06/#btcpay-server-3709
+
+  - title: Discussion about offers-compatible Lightning addresses
+    url: /en/newsletters/2023/11/22/#offers-compatible-ln-addresses
+
+## Optional.  Same format as "primary_sources" above
+see_also:
+  - title: Offers
+    link: topic offers
+
+## Optional.  Force the display (true) or non-display (false) of stub
+## topic notice.  Default is to display if the page.content is below a
+## threshold word count
+#stub: false
+
+## Required.  Use Markdown formatting.  Only one paragraph.  No links allowed.
+## Should be less than 500 characters
+excerpt: >
+  **LNURL** is a set of protocols for communicating information using
+  URLs and HTTPS.  Perhaps the most common use of LNURL is transferring
+  BOLT11 invoices.  A related protocol is **Lightning Addresses** which
+  allow transforming a static identifier that looks like an RFC822 email
+  address into a BOLT11 invoice.
+---
+An upside of LNURL is their flexibility and use of widely understood
+HTTP: a web developer can use their existing skills to interact with LN
+clients.  This allows web developers to handle business logic on the web
+side of their application and only use a LN node to send and receive
+payments.  It also makes it easy for web developers to use LN node
+capabilities in new and interesting ways, such as LNURL-based
+authentication.
+
+A downside of LNURL is that hosted LNURL services may learn information
+about their users' payments and other actions.  For example, many
+Lightning Addresses are managed by centralized services that have the
+capability to intercept payments and potentially track how much a user
+receives through their Lightning Address.  For this reason, alternatives
+to LNURL or additional layers on top of it have been proposed.
+
+{% include references.md %}
+{% include linkers/issues.md issues="" %}
diff --git a/_topics/en/offers.md b/_topics/en/offers.md
index 7aee5f806..20ef55854 100644
--- a/_topics/en/offers.md
+++ b/_topics/en/offers.md
@@ -13,6 +13,8 @@ aliases:
 ## schema for options
 categories:
   - Lightning Network
+  - Invoicing
+  - Wallet Collaboration Tools
 
 ## Required.  Use Markdown formatting.  Only one paragraph.  No links allowed.
 ## Should be less than 500 characters