Skip to content

Latest commit

 

History

History
309 lines (223 loc) · 11.5 KB

NebPay_Introduction.md

File metadata and controls

309 lines (223 loc) · 11.5 KB

Introduction of NebPay SDK

Overview

NebPay SDK provides a unified payment interface for transactions on different platforms. While using NebPay in your Dapp page, you can send transaction throw desktop browser extension and mobile wallet App.

API introduction

The APIs provided by NebPay SDK are as flows：

API Introduction
pay Ordinary transactions between users
nrc20pay NRC20 token transactions
deploy Deploy a smart contract
call Call a smart contract function
queryPayInfo query a transaction result

The first four APIs above are correspond to SendTransaction API, and just refined the usage scenario of SendTransaction. simulateCall is correspond to Call API, which is only used for interactions with browser extension, and is not supported by mobile wallet App.

How to use NebPay

While developing your Dapp, if you want to use NebPay SDK to handle transaction, you need to include nebPay.js into your Dapp page. And then you can use NebPay module to send transactions.

When users using your Dapp whit desktop browsers (chrome), NebPay will call the browser plugin to process the transaction. And when your Dapp is used on mobile phone, NebPay will jump to the wallet App to process the transaction.

Here is an example of using NebPay in you Dapp. Please refer to examples/example.html for more information.

<script src="../dist/nebPay.js"></script>
<script>
    var NebPay = require("nebpay");
    var nebPay = new NebPay();    
    var serialNumber;
    var options = {
        gasLimit: "200000",  //you can customize the gasLimit and gasPrice
        goods: {        //commodity description
            name: "example"
        },
        callback: NebPay.config.testnetUrl,   //tx result query server address
        listener: listenerFunction //specify a listener function for browser extension, which will handle the tx result
    }
    serialNumber = nebPay.pay(to, value, options); //a serialNumber will be returned when calling the NebPay API, then you can query the tx result with this SerialNumber
    
    queryPayInfo(serialNumber, options) //options specifies the query server to query results.
    
    //定义listener函数作为返回信息的回调
    function listenerFunction(serialNumber,result){
        console.log(`the transaction result for ${serialNumber} is: ` + JSON.stringify(result))
    }
</script>

Introduction of API & Parameters

options

NebPay payment APIs has a common parameter options. And here is a detailed introduction of it.

var options = {
	gasLimit: "2000000",  //you can customize the gasLimit and gasPrice
	gasPrice: "20000000000",
	
	goods: {        //Description of this commodity being  traded
		name: "",       //name of commodity
		desc: "",       //description
		orderId: "",    //order ID
		ext: ""         //extended field
	},
	qrcode: {
		showQRCode: false,      //Whether to display QR code information
		container: undefined,    //Specifies the canvas container that displays the QR code. 
		completeTip: undefined, // string of complete payment tip
		cancelTip: undefined // string of cancel payment tip
	},
	extension: {
		openExtension: true //set if need show extension payment mode
	},
	mobile: {
		showInstallTip: true,
		installTip: undefined // string of install NASNano tip
	},
	
	// callback is the server address that records tx results (the results is uploaded by wallet App)
	// we provided tx results query server for testnet and mainnet, and there is a limits to the query frequency.(should less than 20 times per minute)
	//callback: NebPay.config.mainnetUrl,     //tx result query server for mainnet
	callback: NebPay.config.testnetUrl, //tx result query server for testnet
	
	// listener： specify a listener function to handle payment feedback message（just used by browser extension, App wallet doesn't support listener）
	listener: undefined,
	
	// if use nrc20pay API, you need to specify nrc20 params like name, address, symbol, decimals
	nrc20: undefined,
	
	// if debug mode, should open testnet nano and reset the callback
	debug: false
};

In order to deal with different application scenarios, developers can choose to use the browser plugin or NasNano wallet to complete the payment by configuring the options parameter.

The parameters to be used here are qrcode.showQRCode and extension.openExtension. The effect of these two parameters is as follows:

  • The parameter showQRCode determines whether to display the QR code information. Whether it is PC or mobile, when showQRCode = true, the QR code information will pop up on the page.
  • The parameter openExtension determines whether to open the browser plugin. If openExtension = true, NebPay will try to complete the transaction through the browser plugin. And if the plugin is not installed, an alert info will be prompted to tell the user to install the plugin. On the mobile side, the openExtension parameter is neglected.
  • If NebPay is used on the mobile side, it will try to jump to NasNano to complete the payment. If NasNano is not installed, a download reminder will appear.
pay
pay(to, value, options)
parameters：

  • to Destination address of this transfer

  • value Transfer amount in nas.

  • options Refer to options

return
  • serialNumber transaction's serival number, used for query transaction info.
nrc20pay

[Currently not support for mobile wallet app]

nrc20pay(currency, to, value, options)
parameters：

  • currency symbol of NRC20 Token,

  • to Destination address, which is a Nebulas wallet address

  • value Transfer amount, The unit is this NRC20 token.

  • options decimals and Token SmartContract address is required, while Token name and symbol is optional。

options = {
    //nrc20 parameter
    nrc20: {  
        address: "", //contract address of nrc20
        decimals: 0,    //
        name: "",    //Token full name, such as "Nebulas Token"
        symbol: ""  //Token symbol,  such as "NAS","EOS". it's the same with "currency"
    }
}
return
  • serialNumber transaction's serival number, used for query transaction info.
deploy

[Currently not support for mobile wallet app]

deploy(source, sourceType, args, options)
parameters：

  • source source code of smart contract

  • sourceType source type of smart contract

  • args initialization parameters of the SmartContract. parameters are in the form of JSON string of the parameters array, such as["arg"] , ["arg1","arg2"].

  • options Refer to options

return
  • serialNumber transaction's serival number, used for query transaction info.
call
call(to, value, func, args, options)
parameters：

  • to address of smart contract

  • value Transfer amount in nas. Note that the value is transferred to the contract address. If the contract does not have an associated transfer out function, the transferred Nas could not be reached any more.

  • func the function name that will be called

args arguments, in the form of a JSON string of arguments array, such as ["arg"], ["arg1","arg2"].

options Refer to options parameter description

return
  • serialNumber transaction's serival number, used for query transaction info.
queryPayInfo
queryPayInfo(serialNumber, options)
parameters：
  • serialNumber SerialNumber of this transaction, it's a random number of 32 bytes. After sending a transaction with the interface described above, a serial number of the transaction will be returned. Wallet App will uploaded the tx result to a tx query server, and you can use queryPayInfo(serialNumber) to query the tx result.
  • options which specifies the query server to query results.
return

The return value of queryPayInfo is a Promise object. You can handle the result as follows:

var options = {callback: NebPay.config.testnetUrl}
nebPay.queryPayInfo(serialNumber, options)
  .then(function (resp) {
      console.log(resp);
  })
  .catch(function (err) {
      console.log(err);
  });

Note: The query server we provided has limitations on the query frequency, which is 20 times per minute. We suggest that you should set the query period to 5~10s.

Dealing with transaction results

When using wallet App to send tx, wallet App can't return tx result back to Dapp page directly. Hence wallet App will send the tx result to a server. The Dapp side need to record the SerialNumber of a tx, and then use queryPayInfo to query the tx result from this server.

Browser plugins are relatively flexible, it can send messages directly to the page. When using a browser extension to send tx, the extension can send back tx result directly. Hence except querying result with serialNumber, you can also just specify a listener(serialNumber, result) function to handle tx result.

Transaction result message

The tx result queried by queryPayInfo is a JSON string, the format of this JSON is as follows. You should check code === 0, and data.status === 1 to make sure the transaction is packed on chain.

//query failed
{
    "code": 1,  
    "data": {},
    "msg": "payId ZBTSkk74dB4tPJI9J8FDFMu270h7yaut get transaction error"
},
//query succeed
{
    "code": 0,
    "data": {
        "data": null,
        "contractAddress": "",
        "type": "binary",
        "nonce": 136,
        "gasLimit": "30000",
        "gasUsed": "20000",
        "chainId": 1001,
        "from": "n1JmhE82GNjdZPNZr6dgUuSfzy2WRwmD9zy",
        "to": "n1JmhE82GNjdZPNZr6dgUuSfzy2WRwmD9zy",
        "value": "1000000000000000000",
        "hash": "f9549a5c01f50f372607b9fd29bf15d483246578f6cc7008d6e2a537920802e6",
        "gasPrice": "1000000",
        "status": 1,
        "timestamp": 1525508076
    },
    "msg": "success"
}

For browser, if you specified a listener as callback function, then it will be called when a result is returned.

Note Listener function has two parameters function listener(serialNumber, result)

The result information is as follows.

//transaction error, such as user rejected it
"Error: Transaction rejected by user

//transaction successfully sent
{
    "txhash": "a333288574df47b411ca43ed656e16c99c0af98fa3ab14647ce1ad66b45d43f1",
    "contract_address": ""
}

The transaction process using NebPay is as folows:

Example of Dapp using NebPay

Here is a Dapp example Using NebPay: SuperDictionary. It’s source code is on GitHub.

These videos blow explains the payment process of a Dapp using NebPay both on PC and mobile phone.

Youtube:

Or this duplicated video on Chinese vedio website:

More info

If you don't like to use NebPay while developing your Dapp page, you can also use neb.js to get access to Nebulas blockchain directly.