Skip to content

Latest commit

 

History

History
159 lines (109 loc) · 7.28 KB

nip-0002.md

File metadata and controls

159 lines (109 loc) · 7.28 KB
Raw

NIP 2 - Transaction URI Scheme

    NIP: 2
    Title: URI Scheme
    Author: David Garcia <[email protected]>
    Discussions-To: #sig-client
    Comments-URI: https://github.com/nemtech/NIP/issues/6
    Status: Draft
    Type: Standards Track
    Layer: Library
    Created: 2018-12-18
    License: Apache 2.0
    License-Code: Apache-2.0

Table of contents

Introduction

This NIP defines a URI scheme to serve transactions ready to be signed.

Specification

Transaction URI scheme

web+nem://transaction?data=<data>&generationHash=<generationHash>&endpoint=<endpoint>&webhook=<webhook>

Parameter Description Example
data* The transaction serialized in hexadecimal form. A700...4000000
generationHash The network generation hash. Uniquely identifies a network along with the network type. 57F7DA205008026C776CB6AED843393F04CD458E0AA2D9F1D5F31A402072B2D6
endpoint The preferred server to announce the transaction. The application could have another strategy to select the endpoint, omitting this field. http://localhost:3000
webhook The application can provide a URL that identifies the action uniquely. When the transaction is announced from the secure environment, this will send an HTTP POST payload to the URL provided. https://myapp.extension/webhook/10758F6

AnnounceTransaction webhook payload

HTTP Method: POST

Parameter Description Example
action* The event being tracked. AnnounceTransaction
data.hash* The hash of the transaction announced. 1F05...7597451
data.signer* The public key of the transaction signer. EFF9...227CE85

Example

{
  "action": "AnnounceTransaction",
  "data": {
      "hash": "1F05E54DB40DC7C12262F3250F3A428EE6FEC7150DFACB67566B6DD607597451", 
      "signer":"EFF9BC7472263D03EF6362B1F200FD3061BCD1BABE78F82119FB88811227CE85"
  }
}

*required field.

Integration sequence diagram

Motivation

Applications using NEM must be able to prepare transactions ready to be signed from a secure environment. Inspired in Ethereum’s Metamask, the signature of the transaction and its announcement should happen on the client side.

Taking as an example the following user story:

As a customer,
I want to pay for a ticket using my wallet,
so that there is no need to trust the ticket vendor website.

The customer has selected a ticket on the ticket vendor website, and it is ready to pay. The experience suggests that apps built on NIS1 would use one of the following solutions:

A) The ticket vendor offers a client-side app

A user downloads the ticket vendor open-source app in local to sign a transaction. To make the process secure, the user should inspect the downloaded code; checking that transaction is being constructed as expected.

From the UX point of view, having to inspect the code to see what the app does is far from ideal.

B) The customer sends a transaction to a determined address

The user has to define the transaction manually in the NEM wallet.

This approach is secure, but introduces the possibility of making typing mistakes when defining the address, the message, or even choosing the transaction type. Besides, the user spends additional time during the process as it has to set the transaction manually.

C) The customer scans a QR code

A mobile phone scans a QR code served by an application.

This approach is useful, but not complete, since it only works when using two devices, and one of them is a mobile phone.

Furthermore, NEM has different types of transactions, and the previous QR standard only handled transfer transactions.

The aforementioned downsides encourage looking forward to other alternatives. One of the proposed approaches is to define a standard URI scheme.

Design Decisions

Protocol

A URI scheme enables communication between applications and NEM wallets. It can be recognized by desktop and mobile wallets, opening the app with the transaction ready to be signed.

The protocol adds web+ add the beginning of the scheme due to a security requirement for Firefox.

Lightweight library

Creating a URI scheme library that handles custom transaction serialization is expensive because of all the possible permutations coming from maintaining a library per language and new transaction types.

A convenient solution partially exists, making available the internal SDK classes to serialize and deserialize transactions. A lightweight library can be created to parse the Transaction to URI format and vice versa. This library should not be aware of how transactions are serialized/deserialized.

Serialization

Using the internal nem2-sdk functions to serialize transactions, we achieve the following properties:

  • The scheme definition will not change if there is the need to add new types of transactions.
  • Multiple transactions can be announced together using aggregate transactions.

Implementation

Backwards compatibility

NIS1 does not have a known standard URI scheme.

Contributors

Special thanks to @aleixmorgadas, @dexterslabor, @9zero, @jontey, @rg911, @decentraliser for contributing actively to improve this NIP.

History

Date Version
December 18 2018 Initial Draft
January 15 2019 Draft No. 2
March 8 2019 Draft No. 3
April 11 2019 Draft No. 4
April 21 2019 Draft No. 5
May 15 2019 Draft No. 6
Jul 10 2019 Draft No. 7