From bbbfab64e77f508db99db29050664192fec23757 Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Mon, 17 Jun 2024 10:50:01 -0400 Subject: [PATCH] edits --- README.md | 90 +++++++++++++++++-------------------------------------- 1 file changed, 28 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 08811a2..732948d 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,57 @@ -# NFC Push TX -## _NEW_ Coldcard Feature +# NFC Push TX -- Coldcard Feature _(new)_ -This feature allows single-tap broadcast of the freshly-signed transaction. +This feature allows single-tap broadcast of freshly-signed transactions. -`PSBT ==[SD|QR|NFC]==> COLDCARD signed TXN ==[NFC tap]==> Phone Browser ==> Server TXN Broadcast` +`PSBT ==[SD|QR|NFC]==> COLDCARD signed TXN ==[NFC tap]==> Phone Browser ==> TXN Broadcast by node` 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. +Bitcoin node 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` +See `Advanced/Tools > NFC Push Tx` to enable. -## Protocol Spec +## URL Protocol Spec -The COLDCARD needs a URL prefix. To that it appends some values: +The URL contains the signed transaction in +[base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) +and an truncated SHA-256 checksum. -- `t=...` - - this is the transaction, in binary encoded with - [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) +Read the [full specification here](https://github.com/Coldcard/firmware/blob/master/docs/nfc-pushtx.md). -- `&c=...` - - the rightmost 8 bytes of SHA256 over the transaction. Also `base64url` encoded. +## Public Services -- `&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 know of the following services that your Coldcard can use: -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. +- `coldcard.com/pushtx' +- `mempool.space/pushtx' -For COLDCARD backend, the url used is: +You can also host your own backend and there may be other services out there +we don't know about. - https://coldcard.com/pushtx# +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#` -The complete URL with a typical transaction might look like this (but longer): +## Roll Your Own - https://coldcard.com/pushtx#t=AgAAAAMNCxXtp2GVYVhkRXHLMmdZFs4p3kbFK ⋯ ABf&c=uiSVRda-1tw +This [github repo](https://github.com/Coldcard/push-tx) contains the source for +the code hosted at `Coldcard.com/pushtx` for your review or to replace +and personalize. -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. + 4k bytes and the NFC implementation of the phone may also have limits. Truncation + errors will be detected by the checksum. - 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.