Package: coinkite-tap-protocol
Coinkite Tap Protocol and Helper ProgramThis Python library enables easy communication withTAPSIGNER™,SATSCARD™andSATSCHIP™.-==[Request card development sampleshere]==-Repository contents:The protocol specificationPython library for speaking the protocolSupporting documentationExamples/Libraries in other languages:C++https://github.com/nunchuk-io/tap-protocolReact Nativehttps://github.com/bithyve/cktap-protocol-react-nativeDocumentation LinksDocs and Spec subdirectory (./docs)Protocol specificationNFC specificationBest Practices and WarningsDeveloper's Guide and Usage Hints for TAPSIGNEREmulator READMETesting READMEInstallSetup For Everyday UseFirst updatepipto latest version and install wheel (otherwise
legacy setup.py install will be used)pipinstall-UpipwheelInstallcktap, our helpful command-line program, with just:pip install 'coinkite-tap-protocol[cli]'ORIf you just want the Python library by itself, use:pip install coinkite-tap-protocolSetup If You Might Change the CodeDo a git checkoutMake a fresh virtualenv (suggested)Run:# only library
pip install --editable .
# or with cktap cmdline utility
pip install --editable '.[cli]'
# for testing purposes
pip install --editable '.[test]'This installscktapand any changes you make will be immediately
reflected in the installed version.RequirementsPython 3.6 or higherpyscardfor access to smart card readersA supported smart card reader. In theory, all smart card USB CCID class-compliant
devices should work. Our observations:ACS ACR1252U- okay and widely available, and for sale by CoinkiteIdentiv uTrust 3700F- reliable and looks niceHID Omnikey 5022 CL(not 5021) - fast, cute, and smallHID OmniKey 5427 CK- tested Gen1 device, fast, reliable, must disable keyboard wedge via EEM interface on device athttp://192.168.63.99/, when correct will identify as VID:PID076b:5427NOT recommended:ACS ACR122U. It can work, and is widely available, but is not reliable.Seerequirements.txtfile for python packages needed.Ubuntu/Debian NotesInstallingpyscardrequire SWIG and libpcsclite:# run below before installing dependencies with pip# tested on Ubuntu 20.04 (only)sudoapt-getinstallswig
sudoapt-getinstalllibpcsclite-devFedora/Red Hat NotesInstallingpyscardrequires SWIG and the pcsc-lite library:# run below before installing dependencies with pip# tested on Fedora 37 (only)sudodnfinstallswigpcsc-lite-develWindows NotesInstallingpyscardmay require SWIG:Download .zip fromhttp://swig.org.Extract and move intoC:\Program Files.Add that to system PATH.Test:swigat command prompt should work.Runpip install pyscard.FreeBSD NotesTested against 13.0-RELEASE.pkg install py38-pyscard py38-coincurvefollow devfs.conf instructionsinstall usr/ports/devel/libccidaddpcscd_enable="YES"to rc.confpip install base58pip install -e git+https://github.com/coinkite/python-bip32.git@iss27#egg=bip32Make your virtualenv with:virtualenv ENV --system-site-packagespkg install py38-secp256k1(pulls a tragic set of dependencies)NOTE:SWIG is needed to build wheel forpyscard. You may need to runpkg install swig.EmulatorPython code for an emulator which communicates withcktapvia a local Unix socket. It's provided without warranty and isn't
installed by default.cktapprefers to speak to the emulator
if it is running.SeeREADME for emulator.Using the LibrarySATSCARD>>>fromcktap.transportimportfind_first>>>card=find_first()>>>print(card)<CKTapCardSATSCARDviaNFC:26NKY-RWPK4-65YR7-BU4WL>>>>card.address()'bc1q7h0u5yn8y4pajn94ze4gnhz487c8ysvekusqj5'TAPSIGNER>>>fromcktap.transportimportfind_first>>>card=find_first()>>>print(card)<CKTapCardTAPSIGNERviaEMU:2LNJA-NIGMW-Q5AKC-KD5Q2>>>>card.get_xpub('123456')'xpub6DXuQW17LykdXFyEtRrq9Z3MAegRPLAwFovT34afzK6NNHkwJrWCs4Knhrjf1U22QSSbykyzpfRsDZc9ryk9b6VUfGp89vkQw6YjY4CaEQ3'Using the CLIProviding CVCAny command which reveals private key info or changes the state of
the card requires the 6-digit numeric code from the back of the
card (calledCVC,spend code, orStarting PIN Codeon TAPSIGNER).
You can provide this on the command line, or omit it. Commands
requiring the CVC but entered without it will prompt you for the
CVC.  Some commands display limited information without the CVC.
To see more detail, include the CVC on the command line.Most Useful Commandscktap librarycktap --versionGet the version of cktap libraryFor SATSCARDcktap openOpens Bitcoin Core or your other wallet by activating the BITCOIN:addr URL scheme for the current slot of the card.cktap qrDisplays deposit QR code.cktap unsealUnseals the current slot and shows the WIF for funds sweeping.WIF must be imported into a blockchain-aware wallet.cktap balanceCalls a web service to get UTXO and show current Bitcoin balance.Usestord(if running locally) to proxy the request.For TAPSIGNERcktap statusShows status info.cktap setupTells card to pick private key (call once).cktap xpubShows the XPUB in effect.cktap backupSaves the card's XPRV into an AES-128-CTR encrypted file with the current date.cktap change OLDPINCODE NEWPINCODEUse to change the PIN on the cardcktap pathShows the derivation path in effect, by default:m/84h/0h/0hFor SATSCHIPcktap upload -i /path/to/image.jpgcollects artwork meta data (title, description, etc) and uploads signed
result to public serverDetailed Examples% cktap
Usage: cktap [OPTIONS] COMMAND [ARGS]...

  Interact with SATSCARD and TAPSIGNER cards via NFC tap.

  Command marked [TS] are only for TAPSIGNER and [SC] only for SATSCARD. All
  [TS] command also work on SATSCHIP (for artwork).

  You can use "bal", or "b" for "balance": any distinct prefix for all
  commands.

Options:
  -i, --card-ident BLAHZ-  Operate on specific card (any substring is enough)
  -w, --wait               Waits until a card is in place.
  -v, --verbose            Show traffic with card.
  --pdb                    Prepare patient for surgery to remove bugs.
  -e, --emulator-cert      Use root cert key generated by emulator
  --root-cert-pubkey TEXT  Provide alternate root cert key for  certificate
                           checks (testing only)
  --version                Show the version and exit.
  --help                   Show this message and exit.

Commands:
  address  [SC] Show current deposit address
  backup   [TS] Backup private key from card into AES-128-CTR encrypted file
  balance  [SC] Show the balance held on all slots
  certs    Check this card was made by Coinkite: Verifies a certificate...
  chain    Get which blockchain (Bitcoin/Testnet) is configured.
  change   [TS] Change the CVC code (PIN code)
  check    Verify you have the spending code (CVC) correct.
  core     [SC] Show JSON needed to import keys into Bitcoin Core
  debug    Start interactive (local) debug session.
  derive   [TS] Change the subkey derivation path to use (shows xpub)
  dump     [SC] Show state of slot number indicated.
  json     [TS] Dump wallet values in JSON format similar to Coldcard...
  list     List all cards detected on any reader attached.
  msg      Sign a short text message
  open     [SC] Get address and open associated local Bitcoin app to...
  path     [TS] Show the subkey derivation path in effect
  qr       [SC] Show current deposit address as a QR (or private key if...
  setup    Setup with a fresh private key.
  status   Show a few things about status of card
  unlock   Clear login delay (takes 15 seconds)
  unseal   [SC] Unseal current slot and reveal private key.
  upload   [SATSCHIP] Upload an image and artwork's metadata to public...
  url      Get website URL used for NFC verification, and optionally open it
  usage    [SC] Show slots usage so far.
  version  Get the version of the card's firmware installed (but not...
  wif      [SC] Show WIF for last unsealed slot, or give slot number
  xpub     [TS] Show the xpub in use


% cktap list
<CKTapCard SATSCARD: 26NKY-RWPK4-65YR7-BU4WL>
<CKTapCard TAPSIGNER: RUIXK-5XI6U-G55IQ-DVGVI>

% cktap -i RUIXK status
-- TAPSIGNER Card --
Card ident: RUIXK-5XI6U-G55IQ-DVGVI
Birth Height: 723471
Number of backups: 25
Current derivation: m/84h/0h/0h

% cktap -i 26NKY status
-- SATSCARD --
Card ident: XDXKQ-W6VW6-GEQI3-ATSC2
Birth Height: 700001
Active Slot: 7
Address: tb1q779z3npw49qs3rhyk8zhh7l0sgyr9uphm6jlp0SATSCARD% cktap usage
SLOT# |  STATUS  | ADDRESS
------+----------+-------------
  1   | UNSEALED | (use spend code to view)
  2   | UNSEALED | (use spend code to view)
  3   | UNSEALED | (use spend code to view)
  4   | sealed   | bc1qu4vsv2jqgl0y30ehrs4d0dg23xazpgnxdwuqum
  5   | unused   |
  6   | unused   |
  7   | unused   |
  8   | unused   |
  9   | unused   |
 10   | unused   |

% cktap usage 123456
SLOT# |  STATUS  | ADDRESS
------+----------+-------------
  1   | UNSEALED | bc1q4rdps7e8xkaat4ewmmv0hmunsu20s329tf8pdm
  2   | UNSEALED | bc1qe8q7zjtj7utsjlgsq9vn7dl6gqf7kj02tuuec6
  3   | UNSEALED | bc1q9n97zn2nwp7cdhujsgqpgqpv0z49f70lxz9ns2
  4   | sealed   | bc1qu4vsv2jqgl0y30ehrs4d0dg23xazpgnxdwuqum
  5   | unused   |
  6   | unused   |
  7   | unused   |
  8   | unused   |
  9   | unused   |
 10   | unused   |

% cktap qr -o today.svg
(SVG of QR is saved to file)

% cktap addr
bc1qu4vsv2jqgl0y30ehrs4d0dg23xazpgnxdwuqum

% cktap wif -s 1
Enter spending code (6 digits):
p2wpkh:L16cgmhZJWD7fq3eDi3gL7Yko6WYixxZi4f5T3XxxDCF2HnZdHJaTAPSIGNER% cktap status
-- TAPSIGNER Card --
Card ident: RUIXK-5XI6U-G55IQ-DVGVI
Birth Height: 723471
Number of backups: 25
Current derivation: m/84h/0h/0h

% cktap backup 347634
Wrote 109 bytes to: backup-RUIXK-2022-02-16T0926.aes

% hd backup-RUIXK-2022-02-16T0926.aes
00000000  d6 3e 40 59 f0 fd 7a 3d  06 67 a5 94 0b 5d 01 09  |.>@Y..z=.g...]..|
00000010  27 58 c3 2a 1f c1 66 d9  84 84 25 96 af 71 23 a1  |'X.*..f...%..q#.|
00000020  0b bc aa ba c1 a3 98 6d  f2 cd 9c 24 51 8c f7 bf  |.......m...$Q...|
00000030  09 ad 53 0d 9b 07 2b 8e  12 be 73 24 3a 09 a9 3d  |..S...+...s$:..=|
00000040  26 6c 98 59 34 95 aa 78  a1 0b 7a 2b 77 98 1f 7a  |&l.Y4..x..z+w..z|
00000050  d1 cf d6 e6 fd 31 b3 88  1a d9 df 68 03 a3 8b 06  |.....1.....h....|
00000060  db 66 ef d6 ea 5f 5f 08  9a ed f2 2a 71           |.f...__....*q|
0000006dFor more information about specificcktapcommands checkdocs/cli.md