Skip to content

Latest commit

 

History

History
274 lines (187 loc) · 14 KB

README_en.md

File metadata and controls

274 lines (187 loc) · 14 KB
Raw

SimpleWallet protocol document

Version: 1.0

Last updated: 2018.8.17

Scroll to the end for version updates

中文版：https://github.com/southex/SimpleWallet/blob/master/README.md

Introduction

SimpleWallet is a universal protocol for connecting EOS wallets and dapp.we

Currently, there has been rapid development of various wallet applications and dapps in EOS. However, in the actual docking process, the standards of all parties are not unified, and the docking requires much time to complete.

This protocol aims to reduce the development and adaption work of all parties through a low-coupling implementation of a wallet that helps to authorize login and payment of dapp.

This protocol has been built to be compatible with several wallets, and is currently undergoing final tests to ensure their compatibility.

Test page link: http://demo.eossw.io

Function list

  • Login

Scenario 1: The Wallet App scans a QR code for login, which is suitable for dapp on the WEB

Scenario 2: The Mobile App requests login authorization to the Wallet App.

Scenario 3: The Wallet App is embedded and will login to the H5 page (not available temporarily)

  • Payment

Scenario 1: The wallet App scans the code (Web dApp)

Scenario 2: The Mobile App requests payment authorization (Mobile DApp)

Scenario 3: The wallet App is embedded with the H5 page to make payment (not available temporarily)

Flow of the Protocol

1. The Wallet App registers the intercept protocol in the system

The Wallet App first registers the intercept protocol (URL Scheme, appLink) in the Operating System (OS) such that the App of dapp can pull up the wallet application. This is located at: simplewallet://eos.io

Following which, the mobile terminal application of dapp calls this protocol and transfer data to the wallet App. The request format of data transfer is structured as:

simplewallet://eos.io?param={the json data}

2. Login

Scenario 1: The Wallet App scans the QR code for login

Access to dapp website if suitable

Flow chart:

  • The dapp generates QR code, and the wallet scans the login QR code provided by dapp web. The data format of this QR code is json, which contains the following data:
// The QR code data format for login
{
  protocol string   // procotol name, wallet used to distinguish different protocols, this protocol is SimpleWallet
  version     string   // Protocol version information, such as 1.0
  dappName   string   // dapp name
  dappIcon   string   // dapp Icon 
  action     string   // The assignment for login
  uuID       string   // The unique id generated by dapp server for this login verification
  loginUrl   string   // The url on dapp server to accept the login validation information
  expired number   // Qr code expiration time, unix timestamp
  loginMemo string   // Login note information, wallet for display, optional
}
  • The wallet signs the login-related data
  • generate the sign algorithm
  • let data = timestamp + account + uuID + ref //ref is the wallet name, marking the source
  • sign = ecc.sign (data, privateKey)
  • The wallet will POST the signed data to the loginUrl provided by dapp and request the login verification
// request the data format for login validation

{
protocol string // protocol name, wallet is used to distinguish different protocols, and this protocol is SimpleWallet
version string // protocol version information, such as 1.0
timestamp number // current UNIX timestamp number
sign string // eos signature
uuID string // dapp server generated for the unique identity in this login verification
Account string // eos account name
Ref string // source, such as the wallet name
}
  • dapp server receives the data, verifies the sign data, and returns success == true or false; If the validation is successful, the user is set to logged-in the business logic of the dapp
// error return 
{
  code number // error, equal to 0 is successful, greater than 0 means the request failed, dapp returns the specific error code
  error string //prompt message returned
}

Scenario 2: The mobile App of dapp pulls up the wallet App and requests the login authorization

Suitable for dapp mobile (iOS or android) access. Business flow chart is as follows:

  • The mobile terminal of dapp pulls up the wallet App, which requires the login authorization, and transfers the following data to the wallet App in json format:
// the data package structure transfered by dapp to wallet APP

{
protocol string // protocol name, wallet is used to distinguish different protocols, and this protocol is SimpleWallet
version string // protocol version information, such as 1.0
dappName string // dapp name for display in the wallet APP
dappIcon string // dapp icon Url for display in the wallet APP
action string // is assigned to login
uuID string // generated by dapp, used to verify the unique identity of dapp login
loginUrl string // dapp server generated to accept the URL for this login verification
loginMemo string // Note information for login, wallet for presentation, optional
callback string // after the user completes the operation, the wallet callback pulls up the callback URL of the dapp mobile terminal, such as appABC://abc.com?action=login, optional
              // wallet callback with this URL followed by an action (&result) such as appABC://abc.com?action=login&result=1,
        // The value of result is: 0 for user cancel, 1 for success and 2 for failure
}
  • Dapp server receives the data, verifies the sign data, and returns success == true or false; If the validation is successful, the user is set to logged-in in the business logic of the dapp

Scenario 1: The wallet scans the QR code for payment

Business flow chart is as follows:

// the QR code data format generated by dapp for wallet scanning
{
protocol string // protocol name, wallet is used to distinguish different protocols, and this protocol is SimpleWallet
version string // protocol version information, such as 1.0
dappName string // dapp name, for display in the wallet APP, optional
dappIcon string // dapp icon Url for display in the wallet APP, optional
action string // When the payment is assigned as transfer, required
from string // EOS account of payer, optional
to string // EOS account of recipient, required
amount number // amount of transfer, required
contract string //transfer belongs to the token contract account name, required
symbol string // transfer token name, required
precision number // transfer token's precision, the number of digits after the decimal point, required
dappData string // the business parameter information generated by dapp needs to be attached to the memo when transferring, and the format is :k1=v1&k2=v2, optional
          // wallet transfers can also attach ref parameters to indicate the source, such as k1=v1&k2=v2&ref=walletname

desc string // transaction description information, wallet displayed in the payment UI to the user, up to 128 bytes long, optional

expired number //Qr code expiration time, a unix timestamp

callback string // after the user completes the operation, the wallet callback pulls up the callback URL of the dapp mobile terminal, such as https://abc.com?action=login&qrcID=123, optional

	    // wallet callback with this URL followed by operation results (result, txID) such as: https://abc.com?action=login&qrcID=123&result=1&txID=xxx,

	   // result value is: 0 for user cancellation, 1 for success and 2 for failure; txID is the id of this transaction on the mainnet of EOS (if any).

}
  • The wallet assembles the above data and generates an EOS transaction. After the user authorizes the transfer, submits the data to the EOS mainnet; If there are callback parameters, the callback access is performed

The following steps are similar to Scenario 2

  • The Dapp will either check this transaction from the mainnet according to the txID in callback (it cannot completely rely on this method to confirm the user's payment); or the dapp will set up the node to monitor the EOS mainnet by itself, and check whether the tokens are received
  • For popular currencies such as IQ, if the contract name given in the QR code is inconsistent with the official contract name, the wallet side will remind the user and make a second confirmation

Scenario 2: The mobile end of dapp pulls up the wallet App and requests payment authorization

Business flow chart is as follows:

The data package structure transfered by dapp to wallet APP

{
protocol   string   // procotol name, wallet used to distinguish different protocols, this protocol is SimpleWallet
version     string   // Protocol version information, such as 1.0
action     string   // The assignment is transfer when are paying 
dappName   string   // dapp name, for display in wallet APP, optional
dappIcon   string   // dapp Logo Url，for display in wallet APP, optional
from       string   // EOS account of payer, optional
to         string   // EOS account of recipient, required
amount     number   // The amount of transfers，required
contract   string   // The token of the transfer belongs to the contract account name 
symbol     string   // The token name of the transfer，required
precision   number   // The token precision of the transfer, the number of digits after the decimal point，required
dappData   string   // The business parameter information generated by dapp needs to be attached to the memo when transferring, and the format is :k1=v1&k2=v2, optional

    // A ref parameter can also be attached to the wallet transfer to indicate the source，e.g.k1=v1&k2=v2&ref=walletname

desc   string   // Transaction information, wallet displayed in the payment UI to the user, up to 128 bytes long, optional     

      callback   string   // After the user completes the operation, the wallet pulls up the callback URL of the dapp mobile terminal, such as appABC://abc.com?action=login, optional

              // Add operation results (result、 txID) after this URL when wallet callback, such as: appABC://abc.com?action=login&result=1&txID=xxx, 

    // The value of result is: 0 for user cancellation, 1 for success, 2 for failure. TxID is the id of this transaction on the mainnet of EOS (if any).

}
  • The wallet assembles the above data and generates an EOS transaction. After the user authorizes the transfer, the user submits the transfer data to the EOS mainnet; If there is callback, pulls the dapp application

The following steps are similar to Scenario 1

  • The Dapp will either check this transaction from the mainnet according to the txID in callback (it cannot completely rely on this method to confirm the user's payment); or the dapp will set up the node to monitor the EOS mainnet by itself, and check whether the tokens are received
  • For popular currencies such as IQ, if the contract name given in the QR code is inconsistent with the name given by the official contract, the wallet party should remind the user and make a second confirmation
  • There should be reminder for user to identify the source of the QR code in wallet, to avoid the phishing attack.

Error Handling

The code does not equal 0, and the request fails

// error return
{
  code number // error, equal to 0 is successful, greater than 0 means the request failed, dapp returns the specific error code
  error string //prompt message returned
}

Protocol Participants

This protocol is drafted by SouthEX, and jointly discussed and amended by MeetOne, More, TokenPocket, KKWallet and HaloWallet.

Updated Protocol Supporters list: https://github.com/southex/SimpleWallet/blob/master/supporter_list.md

Welcome more wallets and apps to support this protocol and submit your product info to us.

Updated instructions

8.17

  • Added links for testing

  • callback parameter has been added to the payment function

  • two parameters have been renamed as follows

    • expire -> expired
    • callbackUrl -> callback

8.16

Updated callback when the application of dapp calls the wallet App. The wallet only needs to attach result without need to assemble the action parameter

8.15

Simplify the protocol and cancel the info field

Added string type: desc to describe a typical transaction

FAQ

  • How can I prevent users from scanning fake QR codes?

    Although it is possible to avoid phishing by creating a unified DAPP and wallet registrar, it will make the protocol more complex, more centralized, and thus more vulnerable. We recommend that the wallet merchants remind the user to identify the source of the QR code on the interface, improve the user's security awareness, and display the original information of the signature to the user.

  • There is too much information in the QR code. Can you increase the compression algorithm?

    We have tested that we can compress about 20%-30% information about the QR code, the effect is not particularly ideal, so the compression algorithm is not officially included in the protocol. Although the QR code looks too dense, the wallet can be basically recognized. We suggest that if there is too much information in the QR code, DAPP will increase the size when displaying the QR code, so that the user does not have to put the phone close to the screen to improve the recognition speed of the wallet.

  • When verifying the login information, should DAPP verify the activity or the signature of the owner?

    We recommend that DAPP first verify the signature of the activity and, if not, verify the owner. For wallet vendors, it is recommended to sign with active permissions.

  • Why doesn't the SimpleWallet protocol set the relevant login and payment standards for the scene in which DAPP is embedded in the wallet?

    At present, most wallets are developing or have developed their own set of related standards, and the standard is very costly. We recommend that each wallet also refer to the Scatter scheme, which will greatly reduce the adaptation cost of the distributed DAPPs that have been connected to the network.

  • Why doesn't the SimpleWallet protocol set the standard for smart contract calls between wallet and DAPP?

    Ibid.