Share one payjoin concept description across READMEs

payjoin-ffi/CONCEPT.md

@@ -0,0 +1,15 @@
+Payjoin lets Bitcoin senders and receivers interact to make batched
+transactions. The cooperating peers choose the inputs and outputs of the
+transfer together, so the result looks like any other transaction — which
+preserves privacy by poisoning the common-input-ownership heuristic that
+chain surveillance depends on — and the receiver can batch its own
+operations into the same transaction.
+
+These bindings implement both
+[BIP 78 Simple Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki)
+and
+[BIP 77 Async Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0077.md),
+in which sender and receiver exchange the transaction through an
+untrusted directory and never need to be online at the same time.
+
+Learn more at [payjoindevkit.org](https://payjoindevkit.org/).

payjoin-ffi/README.md

@@ -2,7 +2,25 @@
 
 This repository creates Payjoin libraries for various programming languages, all using the Rust-based [Payjoin Dev Kit](https://github.com/payjoin/rust-payjoin) as the core implementation of BIP-77.
 
-Our mission is to provide developers with cross-language libraries that seamlessly integrate with different platform languages. By offering support for multiple languages, we aim to enhance the accessibility and usability of Payjoin, empowering developers to incorporate it into their applications, no matter their preferred programming language.
+<!-- concept:begin (synced from payjoin-ffi/CONCEPT.md; edit there and run payjoin-ffi/contrib/sync-concept.sh) -->
+
+Payjoin lets Bitcoin senders and receivers interact to make batched
+transactions. The cooperating peers choose the inputs and outputs of the
+transfer together, so the result looks like any other transaction — which
+preserves privacy by poisoning the common-input-ownership heuristic that
+chain surveillance depends on — and the receiver can batch its own
+operations into the same transaction.
+
+These bindings implement both
+[BIP 78 Simple Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki)
+and
+[BIP 77 Async Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0077.md),
+in which sender and receiver exchange the transaction through an
+untrusted directory and never need to be online at the same time.
+
+Learn more at [payjoindevkit.org](https://payjoindevkit.org/).
+
+<!-- concept:end -->
 
 ## Supported Target Languages and Platforms
 

payjoin-ffi/contrib/sync-concept.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Sync the shared payjoin concept text (payjoin-ffi/CONCEPT.md) into the
+# marked block of each package README, so every package describes payjoin
+# in the same words. Pass --check to fail on drift instead of rewriting.
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+CONCEPT="$REPO_ROOT/payjoin-ffi/CONCEPT.md"
+READMES=(
+    "payjoin-ffi/README.md"
+    "payjoin-ffi/python/README.md"
+    "payjoin-ffi/dart/README.md"
+    "payjoin-ffi/javascript/README.md"
+    "payjoin-ffi/csharp/README.md"
+)
+BEGIN_MARKER='<!-- concept:begin (synced from payjoin-ffi/CONCEPT.md; edit there and run payjoin-ffi/contrib/sync-concept.sh) -->'
+END_MARKER='<!-- concept:end -->'
+
+CHECK=0
+if [[ ${1:-} == "--check" ]]; then
+    CHECK=1
+fi
+
+status=0
+for readme in "${READMES[@]}"; do
+    path="$REPO_ROOT/$readme"
+    if ! grep -qF "$BEGIN_MARKER" "$path" || ! grep -qF "$END_MARKER" "$path"; then
+        echo "error: $readme is missing the concept markers" >&2
+        exit 1
+    fi
+    tmp="$(mktemp)"
+    awk -v begin="$BEGIN_MARKER" -v end="$END_MARKER" -v concept="$CONCEPT" '
+        $0 == begin {
+            print
+            # prettier pads HTML comments in markdown with blank lines, so
+            # emit the same shape to keep sync and nix fmt at a fixpoint
+            print ""
+            while ((getline line < concept) > 0) print line
+            close(concept)
+            print ""
+            skipping = 1
+            next
+        }
+        $0 == end { skipping = 0 }
+        !skipping { print }
+    ' "$path" >"$tmp"
+    if cmp -s "$path" "$tmp"; then
+        rm -f "$tmp"
+    elif [[ $CHECK -eq 1 ]]; then
+        echo "error: $readme is out of sync with payjoin-ffi/CONCEPT.md;" \
+            "run payjoin-ffi/contrib/sync-concept.sh" >&2
+        rm -f "$tmp"
+        status=1
+    else
+        mv "$tmp" "$path"
+        echo "updated $readme"
+    fi
+done
+exit "$status"

payjoin-ffi/csharp/README.md

@@ -2,7 +2,27 @@
 
 Welcome to the C# language bindings for the [Payjoin Dev Kit](https://payjoindevkit.org/)!
 
-Payjoin lets the receiver of a Bitcoin transfer contribute inputs to the sender's transaction. The result looks like any other transaction, which preserves privacy by poisoning the common-input-ownership heuristic that chain surveillance depends on, and it lets the receiver batch its own operations into the same transaction. These bindings implement both [BIP 78](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki) (synchronous payjoin) and [BIP 77](https://github.com/bitcoin/bips/blob/master/bip-0077.md) (asynchronous payjoin, where sender and receiver exchange the transaction through an untrusted directory and never need to be online at the same time), and ship with native libraries for every supported platform, so no Rust toolchain is required.
+<!-- concept:begin (synced from payjoin-ffi/CONCEPT.md; edit there and run payjoin-ffi/contrib/sync-concept.sh) -->
+
+Payjoin lets Bitcoin senders and receivers interact to make batched
+transactions. The cooperating peers choose the inputs and outputs of the
+transfer together, so the result looks like any other transaction — which
+preserves privacy by poisoning the common-input-ownership heuristic that
+chain surveillance depends on — and the receiver can batch its own
+operations into the same transaction.
+
+These bindings implement both
+[BIP 78 Simple Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki)
+and
+[BIP 77 Async Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0077.md),
+in which sender and receiver exchange the transaction through an
+untrusted directory and never need to be online at the same time.
+
+Learn more at [payjoindevkit.org](https://payjoindevkit.org/).
+
+<!-- concept:end -->
+
+The package ships with native libraries for every supported platform, so no Rust toolchain is required.
 
 ## Install
 

payjoin-ffi/dart/README.md

@@ -2,6 +2,26 @@
 
 Welcome to the Dart language bindings for the [Payjoin Dev Kit](https://payjoindevkit.org/)!
 
+<!-- concept:begin (synced from payjoin-ffi/CONCEPT.md; edit there and run payjoin-ffi/contrib/sync-concept.sh) -->
+
+Payjoin lets Bitcoin senders and receivers interact to make batched
+transactions. The cooperating peers choose the inputs and outputs of the
+transfer together, so the result looks like any other transaction — which
+preserves privacy by poisoning the common-input-ownership heuristic that
+chain surveillance depends on — and the receiver can batch its own
+operations into the same transaction.
+
+These bindings implement both
+[BIP 78 Simple Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki)
+and
+[BIP 77 Async Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0077.md),
+in which sender and receiver exchange the transaction through an
+untrusted directory and never need to be online at the same time.
+
+Learn more at [payjoindevkit.org](https://payjoindevkit.org/).
+
+<!-- concept:end -->
+
 ## Usage
 
 ### Install

payjoin-ffi/javascript/README.md

@@ -2,6 +2,26 @@
 
 Welcome to the JavaScript language bindings for the [Payjoin Dev Kit](https://payjoindevkit.org/)!
 
+<!-- concept:begin (synced from payjoin-ffi/CONCEPT.md; edit there and run payjoin-ffi/contrib/sync-concept.sh) -->
+
+Payjoin lets Bitcoin senders and receivers interact to make batched
+transactions. The cooperating peers choose the inputs and outputs of the
+transfer together, so the result looks like any other transaction — which
+preserves privacy by poisoning the common-input-ownership heuristic that
+chain surveillance depends on — and the receiver can batch its own
+operations into the same transaction.
+
+These bindings implement both
+[BIP 78 Simple Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki)
+and
+[BIP 77 Async Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0077.md),
+in which sender and receiver exchange the transaction through an
+untrusted directory and never need to be online at the same time.
+
+Learn more at [payjoindevkit.org](https://payjoindevkit.org/).
+
+<!-- concept:end -->
+
 ## Usage
 
 ### Install

payjoin-ffi/python/README.md

@@ -2,6 +2,26 @@
 
 Welcome to the Python language bindings for the [Payjoin Dev Kit](https://payjoindevkit.org/)!
 
+<!-- concept:begin (synced from payjoin-ffi/CONCEPT.md; edit there and run payjoin-ffi/contrib/sync-concept.sh) -->
+
+Payjoin lets Bitcoin senders and receivers interact to make batched
+transactions. The cooperating peers choose the inputs and outputs of the
+transfer together, so the result looks like any other transaction — which
+preserves privacy by poisoning the common-input-ownership heuristic that
+chain surveillance depends on — and the receiver can batch its own
+operations into the same transaction.
+
+These bindings implement both
+[BIP 78 Simple Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki)
+and
+[BIP 77 Async Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0077.md),
+in which sender and receiver exchange the transaction through an
+untrusted directory and never need to be online at the same time.
+
+Learn more at [payjoindevkit.org](https://payjoindevkit.org/).
+
+<!-- concept:end -->
+
 ## Install from PyPI
 
 Grab the latest release with a simple: