EvtLink, everiPay, everiPass

This documentation contains detail information about everiPass / everiPay / Payee QR Code.

Contents

Intro

Using the everiToken public blockchain as our core infrastructure, we have created the EvtLink standard which is used to connect payers and payees via a variety of data channels including NFC, Bluetooth, and QR code. Based on EvtLink, everiPay is a payment protocol born for face-to-face token micropayments, and everiPass is a token ownership validation protocol used to operate smart devices (e.g. smart doors). everiPay/everiPass includes the standard of QR code generation and the definition of communication protocol. Users can utilize a wallet app (or even a web page) to generate a dynamic QR Code as proof that he/she is the owner of a specific token (both NFTs / FTs).

Here is a UI example of everiPass:

everiPay

These QR Codes are encoded using a text which has a format called EvtLink. It is a compact format that contains all the information needed for transactions in a short text.

EvtLink is also used to generate a payee QR Code. A Payee QR Code is a static QR Code containing the address of the token receiver. It's another way to pay for tokens based on everiToken. For additional details, have a look at the highlights below.

Highlights

everiPay / everiPass

We have achieved an impressive list of features with our innovations. Here are some highlights regarding EvtLink/everiPay/everiPass:

everiPay/everiPass includes the standard of QR code generation and the definition of communication protocol. Based on everiToken public blockchain with seven characteristics:

  • Instant Clearance, A transaction is a settlement.
  • Decentralization: P2P payment, no centralized platform, no one can modify the data on-chain, and everyone can participate in pricing.
  • Most secure: The data and content in the blockchain cannot be forged or tampered with, so as to maximize the security and protection of user property.
  • Most Convenient: Even if you can’t connect to the Internet, you can complete the transaction. Payer / Payee doesn't need to input the amount of money manually. Payer and payee will receive notification as soon as the transaction is successful.
  • Compatible: everiPay/everiPass support all tokens issued on everiToken. Also, functional day-to-day operations such as a key to open a door are supported. The best part is that you can use it almost everywhere, simply with your phone.
  • Lightning Fast: everiToken has achieved a very high TPS quickly, and transactions can be completed within 1 - 3 seconds depending on the quality of equipment or network.
  • Standardization:Unique from technologies on the wallet side, EvtLink is a cross-wallet, cross-chain, and cross-app standard directly made for the whole ecosystem. You can use any apps to create or parse it.

Based on the above seven characteristics, everiPay / everiPass can provide the most secure, convenient, and user-friendly service in the face-to-face payment industry.

For everiPay / everiPass, the payee must use an app that supports parsing EvtLink and pushing transactions to everiToken. It has been made simple and easy, as we provide easy-to-use APIs and code examples for developers. It is similar to adding AliPay/WeChat support for your store, but even much easier.

Payee QR Code

A Payee QR Code does not support many features that everiPay provides. For example, payers must connect to the Internet to complete a payee QR code transaction, and both payers & payees must input the transaction amount manually. Also, they do not receive an automatic notification when the payment is finished.

However, payees don't need to use an app that supports this payment method. In fact, all payees need to do is simply use a wallet supported by everiToken on their phone to check if they have received the money from the payer. It is suitable for all types and sizes of vendors, as well as exchanges between people.

Using everiPay instead of Payee QR Code is recommended for anyone because it is more transparent, safe, and user-friendly.

How do users use everiPay / everiPass / payee QR Code

For everiPay

  1. The token holder (both NFTs and FTs) uses his/her wallet app (or even a single web page) to generate a series of QR codes (each of them have an embedded EvtLink).
    • The QR code will keep changing every few seconds. Old codes will expire quickly (currently about 20 seconds).
    • The QR code is made up of the current time, the ID of the token he/she wants to use, and the owner's signature for the link.
  2. The recipient uses an everiPay compatible scanner. This could be a mobile phone or any other kind of QR code scanner that is able to read the code and retrieve the decoded EvtLink inside. The link is then included in the transaction and pushed by the machine/phone/scanner.
  3. The BP receives the transaction with the EvtLink inside, checks the signatures, and then executes the action(s) in the link.

For everiPass {for-everipass}

Almost the same as everiPay except for:

  • Normally the scanner is permanently attached to a gateway or a device.
  • After scanning, no transfer is executed. The chain first verifies the ownership of the token to ensure that he/she has permission to pass the gateway/door. Destroying the token after scanning automatically is supported and optional.

For Payee QR Code

  1. Payees show Payee QR Code to the payer. The code could even be printed on paper and posted on a wall because it is static.
  2. The payer then scans the payee QR code using his/her wallet app.
  3. The payer inputs the amount to pay and then executes the transfer action on the chain.
  4. The payee refreshes his/her wallet and confirms the token has been received.

Using everiPay instead of Payee QR Code is recommended because of convenience and safety. .

For everiPay / everiPass

everiToken public chain use everipass action and everipay action to execute the transaction of evtLink. it also provides a struct named evt_link to represent EvtLink. For detail information, please refer to the API / ABI documentation of everiToken.

This will explain the technical process of payments via everiPay / everiPass:

  1. The payer selects a kind of token to use, and the wallet of the payer shows a series of dynamic QR Codes consisting of a unique 128-bit LinkId, a signature of the payer, and the symbol of the token used for payment.

    Note that the LinkId shouldn't be changed during QR code swapping unless the related transaction is executed. Changing the LinkId during this time creates a duplicate payment risk. The chain doesn't allow two actions on EvtLink with the same LinkId.

  2. The wallet of the payer should then continuously query the transaction ID related to the LinkId by calling the API named get_trx_id_for_link_id until it returns a valid transaction ID. After that, the LinkId in the wallet will change the next time it shows a QR code. The wallet should show the transaction result by querying this transaction ID. The wallet apps of payers don't need to send transactions directly.
  3. Meanwhile, the payee scans the QR Code using his/her phone, scanner, or smart gateway. After the evtLink is scanned and parsed, it will be wrapped in an action and then pushed to the chain. Then, all of the chain nodes will synchronize the result, and get_trx_id_for_link_id will return the transaction ID instead of 404.

For Payee QR Code

The Payee QR Code contains a payee's address. The wallet of a payer will post a transaction to transfer the balance of selected token to this address. It's the same as normal transfer transactions.

Development based on evtjs

evtjs fully supports EvtLink as well as everiPay / everiPass / payee code. It is recommended to use evtjs as the groundwork to build your project.

EvtLink is the class you should use to create or parse EvtLink. The function pushTransaction of class APICaller should be used to push the everiPay action onto the chain. For additional details, please refer to the documentation of evtjs project.

We have also published the structure of EvtLink so that you can process it manually.

Each EvtLink has the following struct:

[https://evt.li/]<base42segmentsStream>[_<base42signaturesList>]

-base42signaturesList is required for everiPass / everiPay and not necessary for payeeCode.

[https://evt.li/] is optional prefix and will be ignored when parsing EvtLink. The purpose of adding this prefix is to guide people who didn't use suitable scanners to download a wallet of everiToken, or to know what the QR Code is made for.

We use base42 encoding because this encoding of QR Code is very efficient.

base42 Encoding

Base42 is an encoding algorithm for binary-to-string conversions. It is similar to hexadecimal encoding, but instead uses 42 as its base and correspondingly uses a unique alphabet sequence. The characters in the alphabet are the same as the characters in the encoding of a QR Code's alphanumeric mode, so it's efficient to pack base42-encoded string to a QR Code. This results in a smaller QR Code that allows for more convenient scanning.

Below is the alphabet of base42:

0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ$+-/:*

Note that the index of a char (from zero) represents the numerical sequence of the char too. So A is 10 and : is 41.

For binary starts with one or more zero, you should add 0 to encoded result.

For example, for this byte array:

[ 0, 0, 0, 2, 41, 109, 0, 82, 0 ]

The encoded result is 000AD1KQVMO. The count of prefixed zero is the same as the count of prefixed zero in the original byte array.

Segments Stream

Segments stream has a binary structure which contains one or more segments with a flag as the header:

    <flag><segment><segment><segment><segment><segment>....

Flag represents certain properties of the link. Different flags can be added together. So 7 means ( 1 + 2 + 4 ). This table illustrates in detail:

flag meaning
1 protocol version 1 (required)
2 everiPass
4 everiPay
8 should destroy the NFT after validate the token in everiPass
16 payee's QR code

Below is the struct of each segment:

    <typeKey><value>

typeKey is a unsigned byte.

Different typeKey has different data types for each value.

from to (included) data type
0 20 1-byte unsigned integer
21 40 2-byte unsigned integer (BE)
41 90 4-byte unsigned integer (BE)
91 155 string
156 165 uuid
166 180 byte string
180 255 remained

Here is a brief reference of common used typeKey for convenient.

typeKey flag description of value
42 (uint32) unix timestamp in seconds
43 (uint32) max allowed amount for everiPay
44 (uint32) symbol ID of FT to be paid on everiPay (for example: "1" for EVT)
45 (uint32) symbol id of FT in payee code (for example: "1" for EVT)
91 (string) domain name to be validated in everiPass
92 (string) token name to be validated in everiPass
94 (string) max allowed amount for payment (optionl, only use string format when the amount is greater than 2 ^ 32)
95 (string) public key (address) for receiving points or coins
96 (string) amount received in payee code; should use decimal with proper precision
156 (uuid) link id(128-bit)

base42signaturesList

Signatures is encoded using compact binary format (fixed 65-byte for a signature). If it is a multisign, the decoded base42signaturesList will put them one by one. There is no length prefix or separator during them:

<65-byte sign><65-byte sign><65-byte sign><65-byte sign>...

Each signature has a fixed 65-byte length. The first byte is for recoverParam and is followed by a 32-byte big integer for r, and then a 32-byte big integer for s:

<recoverParam><r><s>

Example

Here is an examples of valid EvtLink (everiPass):

0DFYZXZO9-:Y:JLF*3/4JCPG7V1346OZ:R/G2M93-2L*BBT9S0YQ0+JNRIW95*HF*94J0OVUN$KS01-GZ-N7FWK9_FXXJORONB7B58VU9Z2MZKZ5*:NP3::K7UYKD:Y9I1V508HBQZK2AE*ZS85PJZ2N47/41LQ-MZ/4Q6THOX**YN0VMQ*3/CG9-KX2:E7C-OCM*KJJT:Z7640Q6B*FWIQBYMDPIXB4CM:-8*TW-QNY$$AY5$UA3+N-7L/ZSDCWO1I7M*3Q6*SMAYOWWTF5RJAJ:NG**8U5J6WC2VM5Z:OLZPVJXX*12I*6V9FL1HX095$5:$*C3KGCM3FIS-WWRE14E:7VYNFA-3QCH5ULZJ*CRH91BTXIK-N+J1

Use evtjs we can parse this link and get its structure using parseEvtLink, the result should look like this:

{
  "flag": 11, 
  "segments": [
    {
      "typeKey": 42, 
      "value": 1532709368
    }, 
    {
      "typeKey": 91, 
      "value": "nd1532709365718"
    }, 
    {
      "typeKey": 92, 
      "value": "tk3065418732.2981"
    }, 
    {
      "typeKey": 156, 
      "value": {
        "type": "Buffer", 
        "data": [
          139, 
          90, 
          90, 
          91, 
          249, 
          106, 
          190, 
          191, 
          63, 
          143, 
          113, 
          132, 
          245, 
          34, 
          161, 
          185
        ]
      }
    }
  ], 
  "publicKeys": [
    "EVT6Qz3wuRjyN6gaU3P3XRxpnEZnM4oPxortemaWDwFRvsv2FxgND", 
    "EVT6MYSkiBHNDLxE6JfTmSA1FxwZCgBnBYvCo7snSQEQ2ySBtpC6s", 
    "EVT7bUYEdpHiKcKT9Yi794MiwKzx5tGY3cHSh4DoCrL4B2LRjRgnt"
  ], 
  "signatures": [
    "SIG_K1_K6UKhSMgMdZkm1M6JUNaK6XBGgvpVWuexhUzrg9ARgJCsWiN2A5PeH9K9YUpuE8ZArYXvSWMwBSEVh8dFhHPriQh6raEVc", 
    "SIG_K1_KfdYEC6GnvgkrDPLPN4tFsTACc4nnpEopBdwBsg9fwzG8zu489hCma5gYeW3zsvabbCfMQL4vu9QVbyTHHDLjp43NCNFtD", 
    "SIG_K1_K3CZKdq28aNkGwU9bL57aW45kvWj3CagGgarShLYFg8MVoTTHRbXZwPvyfBf9WN93VGXBPDLdFMmtbKA814XVvQ3QZRVJn"
  ]
}

In this example there are 3 signatures. Users can get public keys that are used to sign on the link using the evtjs's parseEvtLink. It has a flag of 11 (1 + 2 + 8) which represents version 1, everiPass and auto destroy.