tapcards

README

Coinkite Tap Cards Protocol Implementation in Go

This project is a Go language implementation of the Tap Cards protocol, specifically focusing on the Satscard functionality. It does not cover Tapsigner or Satschip functionalities at this time.

Available Satscard Commands

Implemented commands for Satscard include:

• status
• read
• certs
• new
• unseal
• wait

Usage Guide

Initial Steps

The first action with a card is an ISOAppletSelectRequest. The library manages APDU complexities, allowing direct sending of raw bytes. The card’s response should be processed through ParseResponse. This step is not necessary to repeat as long as the card remains powered in the RF field.

Subsequently, run a Request command to generate a byte array for the card. Multiple interactions may be necessary for some commands, with byte arrays from ParseResponse being resent to the card as needed. Once ParseResponse yields no further data, use Satscard to access card information, private keys, etc.

Always verify the factory certificate of the card before trusting any data from it. To do this, run CertsRequest which check the authenticity of the card. This command will also run the read command, which will expose the current receiving address.

Building Mobile Libraries

The Go library can be compiled for mobile platforms, supporting Objective-C on iOS and Java on Android.

Setup Requirements

For iOS

Requires macOS with Command Line Tools or Xcode.

For Android

Requires Android Studio or Command Line Tools, and the installation of Android NDK.

Mobile Compilation Steps

go install golang.org/x/mobile/cmd/gomobile@latest
go install golang.org/x/mobile/bind
gomobile init
gomobile bind -target=ios
gomobile bind -o tapcards.aar -androidapi <API VERSION> -target=android github.com/schjonhaug/tapcards

Examples

In the examples folder, there are two projects using this module. One using the emulator, and the other using physical Satscards.

Development and debug

For the ongoing development and upkeep of this library, it is beneficial to utilise the Python emulator provided by Coinkite. You can integrate the emulator with the library by executing UseEmulator(). Additionally, invoking EnableDebugLogging() will provide valuable information for debugging.

Documentation

Index

• func EnableDebugLogging()
• func UseEmulator()
• type Satscard
  • func (satscard *Satscard) CertsRequest() ([]byte, error)
  • func (satscard *Satscard) ISOAppletSelectRequest() ([]byte, error)
  • func (satscard *Satscard) NewRequest(cvc string) ([]byte, error)
  • func (satscard *Satscard) ParseResponse(response []byte) ([]byte, error)
  • func (satscard *Satscard) ReadRequest() ([]byte, error)
  • func (satscard *Satscard) StatusRequest() ([]byte, error)
  • func (satscard *Satscard) UnsealRequest(cvc string) ([]byte, error)
  • func (satscard *Satscard) WaitRequest() ([]byte, error)

Functions

func EnableDebugLogging

func EnableDebugLogging()

EnableDebugLogging is a function that enables debug logging in the application. It creates a new text handler that writes to the standard error output and sets the log level to debug. It then sets this handler as the default handler for the slog package.

func UseEmulator

func UseEmulator()

UseEmulator is a function that sets the factory root public key string to the specific value associated with the emulator.

Types

type Satscard

type Satscard struct {

	// ActiveSlot is the currently active slot on the card, counting from 0.
	ActiveSlot int
	// NumberOfSlots is the total number of slots available on the card.
	NumberOfSlots int
	// Identity is the human readable identity of the card.
	Identity string
	// ActiveSlotPaymentAddress is the payment address associated with the currently active slot.
	ActiveSlotPaymentAddress string
	// Proto is the protocol version of the card.
	Proto int
	// Birth is the block height of the card.
	Birth int
	// Version is the version of the card.
	Version string
	// ActiveSlotPrivateKey is the private key of the currently active slot.
	ActiveSlotPrivateKey string
	// AuthDelay is the authentication delay of the card.
	AuthDelay int
	// contains filtered or unexported fields
}

Satscard is a struct that represents a Satscard.

func (*Satscard) CertsRequest

func (satscard *Satscard) CertsRequest() ([]byte, error)

func (*Satscard) ISOAppletSelectRequest

func (satscard *Satscard) ISOAppletSelectRequest() ([]byte, error)

ISO Applet Select

func (*Satscard) NewRequest

func (satscard *Satscard) NewRequest(cvc string) ([]byte, error)

func (*Satscard) ParseResponse

func (satscard *Satscard) ParseResponse(response []byte) ([]byte, error)

func (*Satscard) ReadRequest

func (satscard *Satscard) ReadRequest() ([]byte, error)

func (*Satscard) StatusRequest

func (satscard *Satscard) StatusRequest() ([]byte, error)

func (*Satscard) UnsealRequest

func (satscard *Satscard) UnsealRequest(cvc string) ([]byte, error)

func (*Satscard) WaitRequest

func (satscard *Satscard) WaitRequest() ([]byte, error)