From 4890626156b266323299cd9af13ffb320eb7f9ed Mon Sep 17 00:00:00 2001
From: willcl-ark <will@256k1.dev>
Date: Wed, 8 Nov 2023 15:07:22 +0000
Subject: [PATCH] doc: release note for asm repr script changes

---
 doc/release-notes/28824.md | 45 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 doc/release-notes/28824.md

diff --git a/doc/release-notes/28824.md b/doc/release-notes/28824.md
new file mode 100644
index 0000000000000..261862c59eb5c
--- /dev/null
+++ b/doc/release-notes/28824.md
@@ -0,0 +1,45 @@
+# Notable changes
+
+## Updated RPCs
+
+- Script decoding behaviour has been updated which presents in various RPCs.
+
+  Previously, the `asm` representations silently displayed pushed values of 4 bytes or fewer in decimal encoding, while representing values larger than 4 bytes in hexadecimal.
+  This inconsistent behaviour, which was not documented, led to confusion when interpreting various values.
+
+  The following changes have been implemented to provide a unambiguous asm encoding which can (in the future) be decoded:
+
+  - Drop `OP_` prefix from all opcodes:
+
+      e.g. `OP_n` -> `n` (so `-1`, `0`, `1`, ..., `10`, ..., `16`)
+
+      e.g. `OP_CHECKSIG` -> `CHECKSIG`
+
+  - For non-minimal pushes prefix with the opcode and enclose pushed hex value in angle brackets
+
+      e.g. `4c01aa` -> `PUSHDATA1<aa>`
+
+  - For minimal pushes:
+
+    - If > 5 bytes display pushed hex value enclosed in angle brackets
+
+      e.g. `06aabbccddeeff` -> `<aabbccddeeff>`
+
+    - If \<= 5 bytes:
+
+      - If minimally-encoded display pushed value in decimal without angle brackets
+
+        e.g. `0142` -> `66`
+
+      - If not minimally-encoded display pushed hex value enclosed in angle brackets
+
+        e.g. `024200` -> `<4200>`
+
+  The asm can be unambiguously decoded using the reverse rules:
+
+  - A decimal number without angle brackets -> an `OP_N` if applicable, otherwise a direct push of the minimally-encoded form of that number.
+  - `<...>` is turned into a direct push if up to 75 bytes, into `OP_PUSHDATA1` if below 256 bytes, into `OP_PUSHDATA2` if below 65536 bytes, and into `OP_PUSHDATA4` otherwise.
+  - `OPCODE<...>` is turned into a push using the relevant opcode.
+
+  These changes will affect the `asm` output of the `getrawtransaction`, `decodetransaction`, `decodescript` and `decodepsbt` RPCs.
+  See #7996 and #27795 for more discussion.