1 BBN Client Integration 5 th November 2018 Table of Contents Overview ............................................................................................................................................................ 2 Interaction .......................................................................................................................................................... 3 First Paragraph: JSON interaction with Wallet Server ......................................................................................... 4 Ethereum Interaction................................................................................................................................... 4 Wallet Server Authentication ...................................................................................................................... 4 Authentication Methods .............................................................................................................................. 5 <iframe> Method for Javascript .................................................................................................................. 5 <iframe> Method for Javascript – Safari browser ........................................................................................ 7 Direct Call .................................................................................................................................................. 8 JSON-RPC Relay and Signing .................................................................................................................... 8 Second Paragraph: JSON interaction with BBN Server ..................................................................................... 11 1. events .................................................................................................................................................. 12 Events - parameters................................................................................................................................... 13 Events - statuses........................................................................................................................................ 14 2. eventMarkets ....................................................................................................................................... 15 Lays .......................................................................................................................................................... 17 Templates ................................................................................................................................................. 18 Status Codes ............................................................................................................................................. 20 3. Leagues ............................................................................................................................................... 22 4. createPlaceBet ..................................................................................................................................... 23 5. createConfirmBet ................................................................................................................................. 24 6. getPendingBets .................................................................................................................................... 24 7. getPendingResults................................................................................................................................ 24 8. createResultBet .................................................................................................................................... 24 9. getBetHistory....................................................................................................................................... 25 10. addLayMarket ................................................................................................................................. 25
25
Embed
BBN Client Integration - BETR · 2020-01-19 · BETR Android app, BETR progressive web ... with a query string which is the JSON-RPC call URI Encoded. ... The solution
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
1
BBN Client Integration
5th November 2018
Table of Contents Overview ............................................................................................................................................................ 2
<iframe> Method for Javascript .................................................................................................................. 5
<iframe> Method for Javascript – Safari browser ........................................................................................ 7
Direct Call .................................................................................................................................................. 8
JSON-RPC Relay and Signing .................................................................................................................... 8
Second Paragraph: JSON interaction with BBN Server ..................................................................................... 11
Status Codes ............................................................................................................................................. 20
The initial launch of the BetterBetting application architecture will provide:
• Better Betting Node (BBN) service together with Layer UI (https://betrodds.io/) what offers
the layer functionality. User Interface is built by BetterBetting Foundation.
• BBN Client (Bettor UI) what offers the bettor functionality - there will be multiple interfaces:
BETR Android app, BETR progressive web app and Telegram betting bot built by
BetterBetting Foundation and many other user interfaces built by other developers.
• BETR Wallet service. It is envisaged that number of different BETR wallets can be used.
BetterBetting Foundation will build one of the wallets - https://betrwallet.com.
This document describes the JSON interfaces of the BBN service and BETR Wallet service which are used by the Bettor UI and Layer UI.
Bettor UI supports the following functionality:
● login to Wallet service (Bettor UI users will have an account on a wallet server which will
hold the user’s public and private keys)
● displaying sport event markets, selections and lays setup by different layers and prices/odds
● placing bets
● viewing users bet history
It is envisaged that many types of BBN Client will be developed. These will use different technologies with varying capabilities. The initial official release will be a BBN Client based on Xamarin and will work on Android mobile phones (BETR Android app). Thereafter, an official web app https://bet.betrodds.io will be released. BBN Client apps from other developers will also be created and deployed.
Useful links:
• Better Betting Node service and Layer UI: https://betrodds.io/
First Paragraph: JSON interaction with Wallet Server
The BBN Client requires access to the Ethereum blockchain via a Wallet Server with an Ethereum
JSON-RPC Relay and Transaction Signing service (JSON-RPC RTS).
Ethereum Interaction
When the customer wishes to place a bet, the BBN client will need to interact with the Better Betting Contracts on the Ethereum Network without the usual complexity of traditional interface methods such as Metamask or Remix. Furthermore, the method of interaction must work on any platform and / or device (products such as Metamask or Web3 do not work on mobile browsers).
The solution for this interaction is to use a Wallet Server providing a RESTful API for the BBN client which will accept standard JSON-RPC calls as requests, sign the request if necessary, forward the request onto an Ethereum endpoint, receive the response and return the response to the BBN client.
The Wallet Server not only provides a solution to the request / response requirement but will also provide the customer with a secure wallet to hold their ETH and BETR tokens. It is envisaged that there will be many Wallet Servers operated by different companies. The customer will instruct the BBN client to use the Wallet Server where they have an account.
When required, the Wallet Server will sign requests using the customer’s private key which is also held on the Wallet Server. A request that requires signing will involve an Ethereum transaction that changes the Ethereum state such as when a bet is placed.
Wallet Server Authentication
BBN customers will need to have an account with a Wallet Server and will need to have a balance of ETH and BETR tokens to place bets - ETH is used for the transaction costs associated with the submission of a state-change Ethereum transaction and BETR tokens are used as the betting currency for the Better Betting network.
The intention is to separate the BBN client from the Wallet Server authentication process. In other words, the BBN client does not hold the Wallet Server’s authentication tokens or depend on the method of authentication. This approach allows the Wallet Server to carry out their authentication process in any way that is applicable to their operation. This includes 2FA and other third-party forms of Authentication including Facebook and Google authentication.
The primary method that will enable this will be to make Ethereum requests to the Wallet Server via an <iframe>. Alternatively the request can be submitted as a simple HTTP call. If authentication is required, then the Wallet Server will handle the process separately from the BBN client. When authentication has successfully completed, the original request will be forwarded onto the Ethereum endpoint and the response returned as expected. From then on and until authentication is needed again (on timeout or any other reason the Wallet Server decides), Ethereum requests will be submitted and responses received via the Wallet Server.
Usually the Wallet Server will supply some form of authentication token in the form of a Cookie. Subsequent calls to the Wallet Server will automatically supply the Cookie as part of the usual HTTP request process. If the Cookie is invalidated for any reason (such as a timeout) then the Wallet Server will need to request authentication again.
5
Authentication Methods
BBN Clients written in various languages and running on different platforms will have differing capabilities. Therefore, the Wallet Server will need to respond in different ways depending on the client. For example, the BBN Test Client is written using Javascript and uses an <iframe> for all communication with the Wallet Server and the Xamarin BBN client will use Webview which is a browser container.
<iframe> Method for Javascript
For Javascript interaction an <iframe> is recommended which encapsulates the Wallet Server interaction into a window. The issue with the <iframe> approach is to receive the response from the <iframe> call back and pass it up to the BBN Client. The proposed method is to use Event Listeners in the BBN Client which can receive posted messages from an <iframe> window. For example, in the BBN Client an Event Listener is defined and will listen for any event with the property of ‘message’. The origin of the message can be restricted by checking the event origin which in our case only messages from https://betrwallet.com/api/request/ are to be checked.
if (~event.origin.indexOf('https://betrwallet.com/api/request')) {
var return_data = JSON.parse(event.data);
So now the BBN Client is waiting on messages to be posted from the <iframe>. To send messages up to the client, the <iframe> request will return a piece of Javascript which will contain
to send responses to the parent which is the BBN Client. Ok, so that’s how we can communicate between the <iframe> and the BBN Client. To send a request for the current Ethereum gas price, the following JSON-RPC request needs to be sent: {"jsonrpc":"2.0","method":"eth_gasPrice", "params":[],"id":900}
Please note that all wallet requests should have ?js=1 parameter. To initiate the call to the Wallet Server, the <iframe> can be created with a call like this:
Or programmatically like this: $("#iframe_id").attr('src',$("#walletServerURL").val() + "?js=1&qs=" +
encodeURIComponent($("#JSONData").val()));
6
The response from the Wallet Server will contain a piece of Javascript which will automatically execute. Here’s the template which will need to be edited by the Wallet Server before sending. <!DOCTYPE html>
<html>
<head>
<title>JSONRPCQS1 Return</title>
</head>
<body>
<b>BETR.VIP Wallet Server iframe</b>
<br><br>JSON RPC QS 1
<script type="text/javascript">
var endPointURL = "ENDPOINT_URL";
var accountObj = {
walletAddress:"WALLET_ADDRESS",
ETHBalance:"ETH_BALANCE",
BETRBalance:"BETR_BALANCE"
};
accountObj['rpcResponse'] = "JSON_RPC RESULT OBJECT";
The Wallet Server is returning the Wallet Address, the ETH and BETR balances by editing the fields with the values from the Wallet Server Database. The result object of the JSON-RPC call is inserted into the accountObj. The accountObj is the posted to the <iframe> parent for subsequent processing. A point to note is that the responses from the Wallet Server must always contain a HTTP Header to prevent a cross domain error. The HTTP Header name is “Access-Control-Allow-Origin” and is sent with a “*” to allow for all origins.
<iframe> Method for Javascript – Safari browser
For Safari browser authorization should go a bit different. As Safari has no cookies in cross-origin iframes, we need to get token while logging in, and then use this token each request.
In cases where the <iframe> method will not work, such as with the Xamarin Webview, the alternative is to use direct calls and handle the responses programmatically. The Direct Call method consists of one call using the same URIEncoded query string format as with the <iframe> method. If the Wallet Server needs to carry out authentication, then it will return the necessary HTML for the client to display. The Wallet Server will return HTML The response will be like this: <result>
In the eventMarkets API call we have “template” field that indicates how the markets and selections should be rendered.
This field is used by the Bettor UI built by BetterBetting Foundation and is completely optional for you. However, the field might help you to understand how to render different selections (eg number of columns, rows, grouping, filtering). Here is the list of templates built into the API:
• 1x2 – display template with 1 row and 1 column. Example: “Both Teams To Score” market
• 1x3 – display template with 1 row and 3 columns. Example: “Full Time Result” market
19
• 3x3 – display template with 3 rows and 3 columns. Example: “Half Time / Full Time” market
• NX3 – display template with unlimited number of rows and 3 columns. Example: “Correct Score” market
• NX2 – display template with unlimited number of rows and 2 columns. Example: “Goals Over/Under” market
• NX2[{team1}][{team2}] – subtype of NX2 display template with unlimited number of rows and 2 columns. Used for markets where in the selections you have home team and away team. Example: “Asian Handicap” market
20
In most cases eventMarkets API also sorts the selections under every market using the “position” field.
Status Codes
https://betrodds.io/ux/eventMarkets/7231350366221107308 has 3 different status codes: API call status, event status and selection status. The status codes for the event and selection are the same: 1 = open for betting 2 = suspended 3 = resulted Anything higher is internal The API call status will be >0 if something went wrong with an explanation in the text field. Please see the example below:
createConfirmBet is created by the Layer after Bettor places a bet using CreatePlaceBet call. With
this call bet is confirmed in the Ethereum blockchain.
Layer will typically use the following flow:
a. Layer queries for the bets waiting for confirmation by using getPendingResults call
b. Layer confirms the bets using createConfirmBet call
6. getPendingBets
getPendingBets is call used to display bets waiting for Layers confirmation
getPendingBets API: https://betrodds.io/ux/getPendingBets($address) NB! address is Layers wallet address which is used to lay BETR bets.
7. getPendingResults
getPendingResults is call used by the Resultor (often it’s the same entity as Layer) getPendingResults API: https://betrodds.io/ux/getPendingResults($address)
8. createResultBet
createResultBet is call used by the Resultor to result the bets. createResultBet API: https://betrodds.io/ux/createResultBet