Skip to content

Latest commit

 

History

History
296 lines (227 loc) · 13.1 KB

nip-0007.md

File metadata and controls

296 lines (227 loc) · 13.1 KB
Raw

NIP 7 - QR Library Standard Definition

    NIP: 7
    Layer: Library
    Title: QR Library Standard Definition
    Author: Anthony Law <[email protected]>
            Gregory Saive <[email protected]>
    Discussions-To: #sig-client
    Comments-URI: https://github.com/nemtech/NIP/issues/3
    Status: Draft
    Type: Standards Track
    Created: 2018-07-15
    License: MIT

Table of contents

Introduction

The QR Library Standard must allow generating different types of QR codes for contacts, wallet backups or transaction requests.

Following QR code types are identified:

  1. Wallet Import/Export QR code.
  2. Transaction Request QR code for anyone to issue a pre-configured transaction.
  3. Contacts QR code for adding an address to a contacts list.

Motivation

With this NIP, it is intended that the QR code generation processes for Catapult client implementations use a standard way of dealing with QR codes representing several different objects on a Catapult network.

The new version of the Catapult network adds a bit of complexity on top with several types of transactions. Those will all be covered in Transaction Requests.

As to allow better cross-network compatibility, we will also inspect the best ways of adding a replay protection to QR codes such that they will be linked to one type of network and one network guid (if available - nemesis hash if not).

As to provide with cross-client compatible and Catapult-network compatible QR codes, we need to define a standard for definition of QR codes.

Purpose

Following section defines specific purposes of integration and/or generation of QR codes by their respective types. This section will also include examples of QR codes JSON definition as to provide with an overview of available fields and features.

Legacy NEM / NIS1 QR format

Several client implementations for NEM blockchain have come up with a non-standardized way of generating QR codes. The most used definition of QR codes can be found in the nem-library in following implementation of the QRService.

The JSON representation used in this legacy QR code standard defines a transfer transaction request as shows the following example:

{
  "v": 2,
  "type": 4,
  "data": {
    "addr": "",
    "mosaics": [{
      "name": "nem:xem",
      "qty": 10}],
    "msg": "",
    "name": ""
   }
}

Cross-client cross-network compatibility

This library standard aims to produce a cross-client and cross-network compatible QR code generation reference implementation. This is to provide client implementations of the Catapult protocol with a standardized way of handling QR codes.

Legacy QR codes have been known to be only partially compatible between different client implementations. It is up to the client to implement a way of generating QR codes and setting up this library standard will permit better cross-client compatibility.

Additionally, Catapult most likely will introduce many different networks and it is important to define a common QR code standard in order to avoid networks incompatibilities.

Specification

This section describes the specification of our QR code library Standard. QR codes that are to be generated with client implementations of the Catapult network can use this specification as a reference to be NIP-7 compatible.

Catapult QR code format (version 3)

For the Catapult network client implementation, we previously identified different types of QR codes. Following table lists them with their type ID and details about their data schema.

Type ID data schema description
1 address, name Contact Import/Export
2 name, priv_key, salt Accounts Import/Export
3 address, transactionData Transaction requests

Catapult QR code base schema

Our library standard must define fielda that will be present in all QR codes generated with our library. Those fields describe the base schema of QR codes compatible with our standards definition.

Following table lists mandatory fields for Catapult QR Codes compatible with NIP-7:

field type values description
v integer 3 The QR Code version.
type integer 1 | 2 | 3 The QR Code type.
network_id integer 0x68 for Mainnet | 0x98 for Testnet | 0x60 for Mijin | 0x90 for Mijin_test The related Network type.
chain_id string replay protection with 32 bytes nemesis hash of the network.
data object {} The QR code specialized data (AddContractQR, ExportAccountQR, TransactionRequestQR).

Catapult AddContactQR schema

This section describes AddContactQR QR codes data schema with a fields description table and an example:

field type description
data object The QR code data
data.addr string The contact account address.
data.name string The contact name.
Example of Catapult AddContactQR schema
{
  "v": 3,
  "type": 1,
  "network_id": 0x98,
  "chain_id": "E2A9F95E129283EF47B92A62FD748DBA4D32AA718AE6F8AC99C105CFA9F27A31",
  "data": {
    "addr": "NB7CJOPYUMTOV2XNWOWIDD5SBVPVMMM5HKW4M34S",
    "name": "John Invisible",
   }
}

Catapult ExportAccountQR schema

This section describes ExportAccountQR QR codes data schema with a fields description table and an example:

field type description
v integer The QR Code version
type integer The QR Code type (2 = ExportAccountQR)
data object The QR code data
data.encryptedKey string 32 bytes IV prepended to 96 bytes of encrypted payload resulting int: `iv
data.salt string 32 bytes salt that was used for encryption.
Example of Catapult ExportAccountQR schema
{
  "v": 3,
  "type": 2,
  "network_id": 0x98,
  "chain_id": "E2A9F95E129283EF47B92A62FD748DBA4D32AA718AE6F8AC99C105CFA9F27A31",
  "data": {
    "encryptedKey": "b6b016643493648eecaec3e680969322e2af4825b672a6c8977dca23b5d6c0d4a12a831a8de8519c380c15f83652fd20bc685364ab3db170f9212984cf0667af",
    "salt": "6c9ba0c43cd75b4f323947273db9b6f95aef95695197c0b24a5e10116e3923d1",
   }
}

Catapult TransactionRequestQR base schema

This section describes TransactionRequestQR QR codes data schema with a fields description table and an example:

field type description
v integer The QR Code version.
type integer The QR Code type (2 = ExportAccountQR).
data object The QR code data.

The data field for TransactionRequestQR will be different for each supported transaction type. This section will define supported transaction types with their resulting schema specification.

Note: TransactionRequestQR's data (serialization payload / Transaction) object is NIP-2 compatible

Following table lists the currently supported transaction types with links to their respective schema specification:

transaction type link
TransferTransaction Transfer schema
CosignatureTransaction Cosignature schema
TransactionRequestQR specialization schema for Transfers

The schema specialization for transfers will hold the following listed fields, in the data field:

field type description example
type integer (2 bytes) The transaction type. 0x4154
version integer (2 bytes) The transaction format version. 1
deadline uint64 (8 bytes) The transaction deadline. [1,0]
maxFee uint64 (8 bytes) The transaction max payable fee. [0,0]
recipient string The transfer recipient address. Address.createFromRawAddress('NB7CJOPYUMTOV2XNWOWIDD5SBVPVMMM5HKW4M34S').plain()
mosaics array Array of mosaics [{"id": "85BBEA6CC462B244", "amount": [100, 0]}]
message object The transfer message (payload can be empty). {"type": 0, "payload": ""}
Example of Catapult TransactionRequestQR schema specialization for Transfers
{
  "v": 3,
  "type": 3,
  "network_id": 0x98,
  "chain_id": "E2A9F95E129283EF47B92A62FD748DBA4D32AA718AE6F8AC99C105CFA9F27A31",
  "data": {
    "type": 0x4154,
    "version": 1,
    "deadline": [1, 0],
    "maxFee": [0, 0],
    "recipient": "NB7CJOPYUMTOV2XNWOWIDD5SBVPVMMM5HKW4M34S",
    "mosaics": [
      {"id": "85BBEA6CC462B244", "amount": [100, 0]}
    ],
    "message": {
      "type": 0,
      "payload": "54686973206973206120706c61696e2074657874206d657373616765"
   }
}
TransactionRequestQR specialization schema for Cosignatures

The schema specialization for co-signatures will hold the following listed fields, in the data field:

field type description example
hash string The aggregate bonded hash that needs to be co-signed. 6714c22c89c81c656fb771a0492bda7bce6195f7d3ce10fff7cb1b343fdf7671
Example of Catapult TransactionRequestQR schema specialization for Cosignatures
{
  "v": 3,
  "type": 3,
  "network_id": 0x98,
  "chain_id": "E2A9F95E129283EF47B92A62FD748DBA4D32AA718AE6F8AC99C105CFA9F27A31",
  "data": {
    "hash": "6714c22c89c81c656fb771a0492bda7bce6195f7d3ce10fff7cb1b343fdf7671",
  }
}

Implementation

An implementation proposal has been started with following specification:

  • Package name nem2-qr-library at https://github.com/AnthonyLaw/nem2-qr-library
  • interface QrCode with method build()
  • class AddContactQR with implementation for build()
  • class ExportAccountQR with implementation for build()
  • class TransactionRequestQR with implementation for build()
  • Review of the library's OOP structure has been done and is being worked on.

Ongoing Work

  • interface QrCode with method build()
  • class AddContactQR with implementation for build()
  • class ExportAccountQR with implementation for build()
  • class TransactionRequestQR with implementation for build()
  • Review of the library's OOP structure has been done and is being worked on
  • QR library must bridge with nem2-sdk account/addresses objects
  • QR library must bridge with nem2-sdk transaction objects

Backwards compatibility

Legacy QR codes currently being used on the NEM Mainnet (and Testnet) will not be compatible with the propose QR codes definition standard.

Catapult introduces many new features with many newly added transaction types. Yet, the AddContactQR and ExportAccountQR may keep backwards compatibility in adopting the same schema as used in legacy implementations.

References

History

Date Version
July 15 2018 Initial Draft
Aug 6 2018 Second Draft
Apr 8 2019 Third Draft  
Apr 29 2019 Fourth Draft
May 1 2019 Fifth Draft