Casascius Bitcoin POS system/Protocol

DRAFT. See Casascius Bitcoin POS system.

The following messages are defined as being what can be sent between the Bitcoin POS system and its server.

Communication format

To be determined. JSON-RPC over HTTPS would probably work. The terminal is capable of holding onto crypto keys in tamper-protected storage that dumps the keys if the device is opened. This should be used to generate and maintain client-side certificate.

All communications are initiated by the terminal. It polls every 15-60 seconds. This avoids problems with firewalls.

RPC calls

checkin

This is the terminal checking in. The host should respond to tell the terminal the current time, current exchange rate quotes, and provide information about any new alerts (including incoming transactions, configuration changes, or changes to the confirmation status of recent transactions).

From terminal to host:

• Identity
• lastalert: Unique ID of last alert received

From host to terminal:

• Current time local to the terminal (YYYYMMDDHHMMSS)
• Minutes offset from UTC
• Local (non-Bitcoin) currency used on the terminal
• Current market buy rate
• Current market sell rate
• Adjusted market buy rate (e.g. optionally includes configurable markup by merchant)
• Adjusted market sell rate
• Alerts with unique ID greater than lastalert

getaddress

Gets one or more Bitcoin address known to belong to the merchant's wallet. These will be used for incoming Bitcoin transactions. Ideally, the terminal should cache a few of these, since printing an address doesn't need to be a network-dependent operation.

From terminal to host:

From host to terminal:

• The address
• Market rates in effect the moment the address was generated

queryaddress

This command is sent when the terminal scans a private key. It is to ask the server about what funds are available. Only the Bitcoin address is sent to the server, not the private key. The server responds with an amount.

From terminal to host:

• The private key

From host to terminal:

• validflag
• balance

sweep

This command is sent when the terminal confirms a transaction. It asks the server to capture funds from one or more private keys, with an option for returning a portion of funds as change to the customer. The server automatically selects an available wallet address belonging to the merchant.

From terminal to host:

• The private keys
• Nonce
• Change address

From host to terminal:

• successflag
• bitcoin transaction ID
• unique ID of associated alert

The success of the sweep command will be reported as an Alert of type incoming. This ensures that success still gets reported even if the host-to-terminal response is never received.

dispense

This command is sent when the terminal wants to dispense bitcoins to an address. method can be one of printer, magcard, or address, and is intended to record how delivery took place.

From terminal to host:

• amount to dispense
• method
• bitcoin address (if blank, server should generate one)
• authcode
• nonce (so terminal can determine success from alerts in case no response received)

From host to terminal:

• successflag
• bitcoin transaction ID
• bitcoin address
• bitcoin private key (if requested server-side generation)

querynonce

Used so the terminal to follow up on a transaction attempt in case the transaction was sent out but no response was successfully received. Allows the terminal to determine whether a transaction did or did not happen, and if it did not, poisons the nonce so the transaction can't accidentally be committed later.

From terminal to host:

• nonce

From host to terminal:

• completedflag
• bitcoin transaction ID (if applicable)

If completedflag is false, the transaction never took place. The nonce cannot be used again - if the transaction is re-attempted, a new nonce must be generated.

Alerts

An alert is a message to the terminal that tells it that a transaction has occurred. They should be kept by the host in a database so that they can be queried sequentially by the terminal.

Each alert is given an incrementing unique ID. The same number pool might be used system-wide, so the numbering won't be contiguous. What's important is that later alerts have higher numbers than earlier alerts, so when the terminal says it has heard about alert n, it has also heard about all alerts before it as well.

Alerts are retrieved from the server via the checkin RPC call.

incoming

Tells the terminal that a payment has arrived.

Alert fields:

• bitcoinaddress
• arrivedlocaltime (YYYYMMDDHHMMSS)
• arrivedUTC (YYYYMMDDHHMMSS)
• bitcoin transaction ID
• amount of payment
• number of confirmations
• original nonce provided in original associated sweep command, if applicable

confirmed

Tells the terminal that a payment now has a different number of confirmations, or that it has been invalidated due to a double-spend.

It's up to the host to decide how many confirmations to report, but no more than 100 is recommended.

Alert fields:

• bitcoin transaction ID
• new number of confirmations (-1 = transaction invalidated)