NFC API (thoughts and info)

NFC API (thoughts and some info)

To ease the implementations of future BitNFC forks and rewrites, I wanted to have a document with outlined the pseudo code of the current awesome NFC API (nfc.js coded by @wouldgo - Dario) which you can read and it should also be better than my pseudo code if you want to do a cordova/bitcore app - that code in BitNFC works really well

The main problem of BitNFC right now is the support of only one provider (blockchain.com) - and the possibility to write only 1 tag - ideally somebody should fix the current version of BitNFC (shout out if you want to do this - I will be happy to let you merge the code and give you push to master) on BitNFC - there are two a "quick wins" (before a complete featureset)

the two quick wins are:

- support writing multiple tags (TODO: create a new issue)

- change default blockchain api provider to blockcypher (new issue)

and here's an extra one (for par-condicio)

- support multiple blockchain providers

note that this project has been coded in less than 2 weeks by 3 people (doing an online hackathon) but it has a lot of potential

Here's the pseudo-code NFC API - status ok/ko - read() - write()

That's it - simple api

The bitcoin wallet API for the tag is just a bitcore private key saved to the tag at each time -

Instead, the bitcoin wallet API for the device is a wallet which has one private key (TODO: Add HD wallet - improvement #next - #anonymity - #fungibility) being saved to the browser localStorage (that in the case of the codrova app is sandboxed into the cordova environment, thus is not available by other apps)

Important: the private key is saved to the device and is being used just to sign transactions ()

The wallet can be funded "by itself" because it's made of an address (remember that a wallet is just keypair). Every user in bitcoin can send a transaction to that address to fund it.

# statuses and calls

cs/rb/pseudo:

NFC_API status: "ok"

NFC_API status: "ko"

NFC_API write: "success"

NFC_API read

js:

NFCApi.status(connection: "ok")

NFCApi.status(connection: "ko")

NFCApi.read() // => "5pvtKey"  ---- ?sms:5pvtKey ---- "message" --- (optional: error read timeout in callback based call)

NFCApi.write("message") // => {success: "true"} ---  { ok: true } ---- { error: {} } ---  ...

brief explanation on the 3/4 api calls

Status

connection ok / ko is used to bring the knowledge of the current status of the NFC from the device

for example when the NFC feature is activated - ideally the full user experience will pop up a notification (syle: toast for example) )

Write

write is writing on the nfc tag -- this action should have a throttle delay so you can't scan a tag (fnThrottle = _.throttle(fn))

Read

read is reading a tag to get its contents

in the case of BitNFC a key is written to the tag and read reads its context

the private key should be saved in the WIF format instead of bitcore.PrivateKey().toString()

note that it bitcore the WIF format is achieved by bitcore.PrivateKey().toWIF()

Wallet actions

The wallet has only one action, which is sweep()

pseudo code: Wallet.current().sweep()

Wallet.current() probably is a singleton if you're implementing this via oo - it just loads (or generate) the wallet private key - generation happens locally via bitcore-lib (but it could happen via any bitcoin libs local to your programming language / platform)

sweep() comes from "sweep" which in bitcoin terms means spending all the funds contained in one address (wallet / keypair) you "approach" to your current one (in this case your NFC mobile app - the BitNFC one)

TODO: there is the important need of making all the read/write operations throttled and to add optional, activatable logs (messages/event) to log their statuses (always whitout revealing the private key contained into the tag)

** the main point of this effort of highlighting the current api is to show the simplicity of the nfc process

a more complete nfc process will read the tag and ask to the user what to do with it**

# actions


module Actions

  # prerequisite:
  #   GEN  - generate and write a new private key
  #   LOAD - load and write a new private key
  def nfc_write(privateKey, writeOkEvt, writeErrEvt)
    # $window.nfc.write(messageToSend, onWriteSuccess, onWriteError);
  end

  def nfc_read
    data = "X...."
    # $window.nfc.bytesToString(ndefMessage[0].payload)
    #
    # post-processing (data-transformation)
    #
    #
    data = [1..-1]
  end

end

const c = console

c.log("init")

class NFCApi {
  nfc_read()   // "5message..."

  nfc_write()  // status: "ok", message: "the >message< has been written to the tag"

  nfc_status() // connection: "ok" / connection: "ko"
}

c.log("loaded")

TODO: this doc needs to be finished :D - check for errors and unfinished sentences ^^

TODO: also a check of all types of nfc tags (some need to be pre-formatted otherwise the tag cannot be re-read, leading to a broken api - test new tags only with few 0.2 millibits

720kb / BitNFC