Merge pull request #6559 from mempool/natsoni/taptree-doc

Add detailed data formats and verification process to Taptree doc

frontend/src/app/docs/api-docs/api-docs.component.html

@@ -478,16 +478,31 @@
 
 <ng-template type="how-can-i-share-or-verify-taproot-scripts">
   <p>A third party may need to verify unpublished script paths for a Taproot address. One option is to reveal each script by spending coins through every path on-chain, but this hurts privacy and may not be possible if a script is timelocked, for example.</p>
-  <p>A more private option is to share the Taproot data directly with the third party using the Taproot Tree widget. On the address page, use the <fa-icon [icon]="['fas', 'code-fork']" [fixedWidth]="true"></fa-icon> icon to open a form where Taproot data can be entered. The same data can also be shared directly in the URL fragment:</p>
+  <p>Alternatively, you can share the Taproot data privately with the third party, using the Taproot Tree widget to fill in scripts that are not already known from on-chain spends. On the <a [href]="('/address/' | relativeUrl:'mainnet') + faqTaprootAddress">address page</a>, use the <fa-icon [icon]="['fas', 'code-fork']" [fixedWidth]="true"></fa-icon> icon to open a form where unpublished Taproot leaves can be passed.</p>
+  <p>The following formats are supported:</p>
+  <ul>
+    <li><code>PSBT</code>: hex or base64-encoded PSBT involving this address. It should include input <code>PSBT_IN_TAP_LEAF_SCRIPT</code> records, output <code>PSBT_OUT_TAP_TREE</code> and <code>PSBT_OUT_TAP_INTERNAL_KEY</code> records, or both.</li>
+    <li><code>Taptree</code>: hex or base64-encoded <code>PSBT_OUT_TAP_TREE</code> value. If the internal key of the address is not known from an on-chain spend, provide it in the <code>Internal Key</code> field.</li>
+    <li><code>Tapleaves</code>: comma-separated <code>PSBT_IN_TAP_LEAF_SCRIPT</code> records, in the format <code>&lt;control-block&gt;:&lt;script&gt;&lt;leaf-version&gt;</code>.</li>
+  </ul>
+  <p>You can also embed the data directly in the URL fragment. Click the links below for examples:</p>
   <ul>
-    <li><a [href]="('/address/' | relativeUrl:'mainnet') + faqTaprootAddress + '#taptree=01c0462060e531bc7b23e145618de9d21a9240e9cf1909a32e77b688f36ec67901500d58ac202edfc0c6e4166b1d5497d9c7a72e7ed4c83fe03596fe5ce5edf7311ddeddf3b1ba529c01c02220ab46f1bd685e9c768cca20e5b9a5972b4e1ebab9afda82012ffd0a09d340eb39ac'"><code>/address/&lt;address&gt;#taptree=&lt;taptree&gt;</code></a></li>
     <li><a [href]="('/address/' | relativeUrl:'mainnet') + faqTaprootAddress + '#psbt=cHNidP8BAF4CAAAAAaw0pDKziErd65x14VlMyr0dk40sbfnsamlaosoIMs/uAAAAAAD9////ARwUAAAAAAAAIlEgnvbZpjy+K9OYazdE0ZpDDp7aT7dUorK7Vj6Y0E7uqqkAAAAAAAEAXgIAAAABgLeH7oKnqJhBXimT6kZD0aqj5ruNbph8lB9VAPQr3sIAAAAAAP3///8BvBQAAAAAAAAiUSBJJVwiFU5hOZBwUBPCN2A/wOQ9ck4K4MpzwtCbYVTCpQAAAAABASu8FAAAAAAAACJRIEklXCIVTmE5kHBQE8I3YD/A5D1yTgrgynPC0JthVMKlQhXAitqBVHimnBwQrybUyzcOpT3P3sL9AwCmrjUQQVEzwSbXHdkZm5ahJwmj+qvwMlpwzuB/N8Mh7VP8L72/Mr/zS0cgYOUxvHsj4UVhjenSGpJA6c8ZCaMud7aI827GeQFQDVisIC7fwMbkFmsdVJfZx6cuftTIP+A1lv5c5e33MR3e3fOxulKcwEIVwIragVR4ppwcEK8m1Ms3DqU9z97C/QMApq41EEFRM8EmHxKGqo8QrcKRJ/V/AofE38r3/E00jTURzyXSM2o8QowjIKtG8b1oXpx2jMog5bmllytOHrq5r9qCAS/9CgnTQOs5rMABFyCK2oFUeKacHBCvJtTLNw6lPc/ewv0DAKauNRBBUTPBJgAA'"><code>/address/&lt;address&gt;#psbt=&lt;PSBT&gt;</code></a></li>
+    <li><a [href]="('/address/' | relativeUrl:'mainnet') + faqTaprootAddress + '#taptree=01c0462060e531bc7b23e145618de9d21a9240e9cf1909a32e77b688f36ec67901500d58ac202edfc0c6e4166b1d5497d9c7a72e7ed4c83fe03596fe5ce5edf7311ddeddf3b1ba529c01c02220ab46f1bd685e9c768cca20e5b9a5972b4e1ebab9afda82012ffd0a09d340eb39ac'"><code>/address/&lt;address&gt;#taptree=&lt;taptree&gt;</code></a></li>
     <li><a [href]="('/address/' | relativeUrl:'mainnet') + faqTaprootAddress + '#tapleaf=c08ada815478a69c1c10af26d4cb370ea53dcfdec2fd0300a6ae3510415133c126d71dd9199b96a12709a3faabf0325a70cee07f37c321ed53fc2fbdbf32bff34b:2060e531bc7b23e145618de9d21a9240e9cf1909a32e77b688f36ec67901500d58ac202edfc0c6e4166b1d5497d9c7a72e7ed4c83fe03596fe5ce5edf7311ddeddf3b1ba529cc0'"><code>/address/&lt;address&gt;#tapleaf=&lt;control-block&gt;:&lt;script&gt;&lt;leaf-version&gt;</code></a></li>
   </ul>
   <div class="taproot-faq-widget" *ngIf="faqTaprootInfo?.full as taprootInfo">
     <app-taproot-address-scripts [address]="faqTaprootAddress" network="mainnet" [scripts]="taprootInfo.scripts"></app-taproot-address-scripts>
   </div>
-  <p>Cryptographic checks on the provided data are done in the browser so the verifier can independently confirm that the provided scripts commit to the Taproot output key for the address.</p>
+  <p>The provided tapleaves are cryptographically verified against the address before being added to the Taproot Tree widget. Verification happens entirely in the browser, using the following process for each leaf derived from passed data:</p>
+  <ul>
+    <li>Script, leaf version, Merkle branch and internal key are extracted.</li>
+    <li>Script and leaf version are used to compute the TapLeaf hash.</li>
+    <li>Tapleaf hash and Merkle branch are used to compute the Taproot Merkle root.</li>
+    <li>Taproot Merkle root and internal key are used to compute the Taproot output key.</li>
+    <li>Taproot output key is used to derive the Taproot address.</li>
+    <li>The leaf is added to the Taproot Tree if the derived address matches.</li>
+  </ul>
 </ng-template>
 
 <ng-template type="what-are-sigops">