From 5a1adc441f2bb9fb9aab30fe10d576433cf332ea Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Fri, 14 Jun 2024 10:12:40 -0400 Subject: [PATCH] more --- README.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 101 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6eb191d..08811a2 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,101 @@ -# push-tx -NFC Push TX +# NFC Push TX +## _NEW_ Coldcard Feature + +This feature allows single-tap broadcast of the freshly-signed transaction. + +`PSBT ==[SD|QR|NFC]==> COLDCARD signed TXN ==[NFC tap]==> Phone Browser ==> Server TXN Broadcast` + +Once enabled with a URL, the COLDCARD will show the NFC animation +after signing the transaction. When the user taps their phone, the +phone will see an NFC tag with URL inside. That URL contains the +signed transaction ready to go, and once opening in the mobile +browser, that URL will load. The landing page will connect to a +Bitcoin node (or similar) and send the transaction on the public +Bitcoin network. + +This feature is available on Q and Mk4 and requires NFC to be enabled. +See `Advanced/Tools > NFC Push Tx` + +## Protocol Spec + +The COLDCARD needs a URL prefix. To that it appends some values: + +- `t=...` + - this is the transaction, in binary encoded with + [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) + +- `&c=...` + - the rightmost 8 bytes of SHA256 over the transaction. Also `base64url` encoded. + +- `&n=XTN` + - if, and only if, the COLDCARD is set for Testnet, this value is appended to + indicate that the transaction is for Testnet3 and not MainNet. + - when RegTest is enabled, the value will be `XRT` + +We provide a few default URL values to our customers, including one backend we +will operate on `colcard.com`. The URL can also be directly entered by the +customer. On the Q, it can be scanned from a QR code. + +For COLDCARD backend, the url used is: + + https://coldcard.com/pushtx# + +The complete URL with a typical transaction might look like this (but longer): + + https://coldcard.com/pushtx#t=AgAAAAMNCxXtp2GVYVhkRXHLMmdZFs4p3kbFK ⋯ ABf&c=uiSVRda-1tw + +We are using hash symbol here so that our server logs do not get +contaminated with the arguments. The landing page uses javascript +to read the hash part of the URL and decodes from there. If you +prefer, your URL can end with `?` and then the arguments will be +sent by the phone's browser to your server. Your processing can be +entirely done in the backend in this case. + +## Expectations for the Backend + +Your code should decode the transaction and check the SHA-256 hash +matches. If it does not match, or if `c` value is missing, assume +the URL has been truncated and report that to the user. + +Once decoded, your code should immediately broadcast the transaction. +A confirmation step is not required in our opinion. Once it is +submitted to Bitcoin Core (or other API), any status response should +be decoded and shown to the user so they know it is on it's way. +If it was not accepted, please report the error to the user as +clearly as possible. + +Next, it would make sense to either link to the TXID on a block +explorer to provide further proof that it has been sent and that +it is now waiting in the mempool. + +## Backend Implementations + +- Mempool.space's [implementation of this feature](https://github.com/mempool/mempool/pull/5132). + +- A single-file (html and javascript) file is available + at [coldcard.com/static/coldcard-pushtx.html](https://coldcard.com/static/coldcard-pushtx.html). + You can host this file anywhere your phone can reach, and then use that URL in your + COLDCARD settings. It uses your phone's browser to submit directly + to `mempool.space` and `blockstream.info` sites (both at same time). It is equivalent + to the page hosted at `https://coldcard.com/pushtx#` + +### Notes + +- Complete URL might be as large as 8,000 bytes. Some web servers will not support beyond + 4k bytes and the NFC implementation of the phone may also have limits. +- The service URL provided must end in `?` or `#` or `&`. +- `base64url` values from COLDCARD will not have padding (`=` bytes) at end. +- POST cannot be used directly because the expect the phone to do a GET on the URL provided. +- Honest backends will not log the IP address of incoming transactions, but there is + no way to enforce that, and CloudFlare sees all. + +## Example URL + +``` +https://mempool.space/pushtx#t=AgAAAAOHqK3w3hC6PSC0buthnJA5R9Y88WAlEvm9cifNVUPhIwAAAABqRzBEAiB-M9YprNYoohqHdQHg4wY_qcEMwDmyIQH8prykk8-0KwIgARxcojKrtixicouiUxhk4jQq_MAl11ptIgHDlRjgk5ABIQM4bgMAVDbDSr_9CvLjbg5nxrWnDGI-kVmkfL81GXZtCf____8OaH0RxW7DjZKdIF6rvbHvvyFGCBQ0PTgpx20nA_wbLgAAAABqRzBEAiBwUFigORJDPK8ptnYPAntjV-RUn1jAuzphicQstwVv-QIgEbMC8FWXQ5Jve5DaAqKJsqoj3peK83iub_oOkmbiYg4BIQO5Ehn2t0oUG3hnK4cBnwCwMc33DcdJ8aSMWzRQ_wjZL_____-UG6M-eBeAun-EZp6EbVypvVJ3mXCQrN_fUDn-kwoEnQAAAABqRzBEAiAgFAtVTpQYTKplc9NuV7Ws7ZFYeNO8BCS4ozgWrgd2ogIgGTTcw98xQdcGWeWQhVfVm_vZorBIOYovQPQeK0Lg9t8BIQLPWPioVWvj1z4NMHBCkeirYOUalCa83wbSH0CREnGZvv____8CjM_wCAAAAAAZdqkUIJA8_yqzaj0NzhvYVEIBno5gETGIrIzP8AgAAAAAGXapFEaV7xTyleuEX9OejdlUlsz7RTr0iKwAAAAA&c=hre47vyMC78&n=XTN +``` + +- this transaction doesn't have valid inputs, and will cause an error +- mempool.space will redirect this to a testnet endpoint (because ends with `n=XTN`) + +