diff --git a/README.md b/README.md index fbc6fc7..9cee824 100644 --- a/README.md +++ b/README.md @@ -1,237 +1,47 @@ -# SimpleWallet 协议文档 - -版本:1.0 - -协议最后更新:2018.8.31 - -English Version: https://github.com/southex/SimpleWallet/blob/master/README_en.md ( EOSShenzhen 翻译) - -## 简介 -SimpleWallet是一个EOS钱包和dapp的通用对接协议。 - -目前EOS的钱包应用众多、dapp也在快速发展中,在实际对接过程中,各方标准不统一,对接耗时耗力。 -遵照此协议,可以减少各方开发适配工作,低耦合的实现钱包对dapp进行登录授权和支付。 -钱包接入方可在 https://www.southex.com 进行在线测试。 - -## 协议发起方 -本协议由SouthEX起草,MeetOne、More、TokenPocket、KKWallet、HaloWallet 共同参与讨论和修改。 - -除以上五家钱包之外,目前正在接入的钱包商还包括:EOS LIVE钱包、番茄钱包、PocketEOS及韩国的coinus等。 - -目前接入此协议的名单:https://github.com/southex/SimpleWallet/blob/master/supporter_list.md - -欢迎更多的钱包和dapp接入此协议,并向我们提交你们的产品信息。 - -## 功能列表 -- 登录 -1. 场景1:钱包App扫二维码进行登录,适用于WEB版dapp -2. 场景2:dapp的移动端APP拉起钱包APP,请求登录授权 -3. 场景3:钱包APP内嵌dapp的H5页面,进行登录(暂无) - -- 支付 -1. 场景1:钱包扫码支付,适用于WEB版dapp -2. 场景2:dapp的移动端拉起钱包APP请求支付授权 -3. 场景3:钱包APP内嵌dapp的H5页面,进行支付(暂无) - -## 协议内容 - -### 1. 钱包APP在系统注册拦截协议 - -钱包APP应在操作系统内注册拦截协议(URL Scheme、appLink),以便dapp的APP拉起钱包应用。 - -以下为安卓端的协议接入方法: - -拦截协议为:simplewallet://eos.io - -dapp的移动端应用可以调用此协议,传递数据给钱包APP,传递数据的请求格式为: - -simplewallet://eos.io?param={json数据} - -对于iOS端,由于其app之间的调用机制和安卓差别很大,制定统一的协议非常复杂,且目前基于iOS的dapp和钱包很少,因此SimpleWallet不对iOS上进行协议统一。各方钱包和dapp可自行协商对接方法。 - -### 2. 登录 - - -#### 场景1:使用钱包扫码二维码登录 -> 适合dapp的网站接入。 -> -> 业务流程图如下: - -![image](http://on-img.com/chart_image/5b658d5de4b0be50eacf8f0c.png?t=1) - -- dapp生成二维码,钱包扫描dapp web提供的登录二维码,此二维码的数据格式为json,包含以下数据: -``` -// 登录的二维码数据格式 -{ - protocol string // 协议名,钱包用来区分不同协议,本协议为 SimpleWallet - version string // 协议版本信息,如1.0 - dappName string // dapp名字 - dappIcon string // dapp图标 - action string // 赋值为login - uuID string // dapp server生成的,用于此次登录验证的唯一标识 - loginUrl string // dapp server上用于接受登录验证信息的url - expired number // 二维码过期时间,unix时间戳 - loginMemo string // 登录备注信息,钱包用来展示,可选 -} -``` -- 钱包对登录相关数据进行签名 -``` -// 生成sign算法 -let data = timestamp + account + uuID + ref //ref为钱包名,标示来源 -sign = ecc.sign(data, privateKey) -``` -- 钱包将签名后的数据POST到dapp提供的loginUrl,请求登录验证 -``` - // 请求登录验证的数据格式 -{ - protocol string // 协议名,钱包用来区分不同协议,本协议为 SimpleWallet - version string // 协议版本信息,如1.0 - timestamp number // 当前UNIX时间戳 - sign string // eos签名 - uuID string // dapp server生成的,用于此次登录验证的唯一标识 - account string // eos账户名 - ref string // 来源,如钱包名 -} -``` -- dapp server收到数据,验证sign签名数据,并返回结果code;若验证成功,则在dapp的业务逻辑中,将该用户设为已登录状态 - -``` -// 错误返回 -{ - code number //错误符,等于0是成功,大于0说明请求失败,dapp返回具体的错误码 - error string //返回的提示信息 -} - -``` -#### 场景2:dapp的移动端应用拉起钱包App,请求登录授权 -> 适合dapp的移动端(iOS或安卓端)接入。业务流程图如下: - -![image](http://on-img.com/chart_image/5b6591fbe4b0edb750f9a364.png?t=1) -- dapp的移动端拉起钱包APP要求登录授权,并传递给钱包App如下的数据,数据格式为json: -``` -// dapp传递给钱包APP的数据包结构 -{ - protocol string // 协议名,钱包用来区分不同协议,本协议为 SimpleWallet - version string // 协议版本信息,如1.0 - dappName string // dapp名字,用于在钱包APP中展示 - dappIcon string // dapp图标Url,用于在钱包APP中展示 - action string // 赋值为login - uuID string // dapp生成的,用于dapp登录验证唯一标识 - loginUrl string // dapp server生成的,用于接受此次登录验证的URL - loginMemo string // 登录的备注信息,钱包用来展示,可选 - callback string // 用户完成操作后,钱包回调拉起dapp移动端的回调URL,如appABC://abc.com?action=login,可选 - // 钱包回调时在此URL后加上操作结果(&result),如:appABC://abc.com?action=login&result=1, - // result的值为:0为用户取消,1为成功, 2为失败 -} -``` -- dapp server收到数据,验证sign签名数据,返回success == true或false;若验证成功,则在dapp的业务逻辑中,将该用户设为已登录状态 - -### 3. 支付 -#### 场景1:钱包扫描二维码进行支付 -> 业务流程图如下: - -![image](http://on-img.com/chart_image/5b6594bae4b053a09c24fa9a.png?t=1) - -``` -// dapp生成的用于钱包扫描的二维码数据格式 -{ - protocol string // 协议名,钱包用来区分不同协议,本协议为 SimpleWallet - version string // 协议版本信息,如1.0 - dappName string // dapp名字,用于在钱包APP中展示,可选 - dappIcon string // dapp图标Url,用于在钱包APP中展示,可选 - action string // 支付时,赋值为transfer,必须 - from string // 付款人的EOS账号,可选 - to string // 收款人的EOS账号,必须 - amount number // 转账数量,必须 - contract string // 转账的token所属的contract账号名,必须 - symbol string // 转账的token名称,必须 - precision number // 转账的token的精度,小数点后面的位数,必须 - dappData string // 由dapp生成的业务参数信息,需要钱包在转账时附加在memo中发出去,格式为:k1=v1&k2=v2,可选 - // 钱包转账时还可附加ref参数标明来源,如:k1=v1&k2=v2&ref=walletname - desc string // 交易的说明信息,钱包在付款UI展示给用户,最长不要超过128个字节,可选 - expired number // 二维码过期时间,unix时间戳 - callback string // 用户完成操作后,钱包回调拉起dapp移动端的回调URL,如https://abc.com?action=login&qrcID=123,可选 - // 钱包回调时在此URL后加上操作结果(result、txID),如:https://abc.com?action=login&qrcID=123&result=1&txID=xxx, - // result的值为:0为用户取消,1为成功, 2为失败;txID为EOS主网上该笔交易的id(若有) -} -``` -- 钱包组装上述数据,生成一笔EOS的transaction,用户授权此笔转账后,提交转账数据到EOS主网;若有callback参数,则进行回调访问 -- dapp可根据callback中的txID去主网查询此笔交易(不能完全依赖此方式来确认用户的付款);或dapp自行搭建节点监控EOS主网,检查代币是否到账 -- 对于流行币种如IQ,如果二维码中给出的contract名和官方的合约名不一致,钱包方要提醒用户,做二次确认 -- 钱包应该提醒用户注意辨别二维码的来源,避免被钓鱼攻击 - - -#### 场景2:dapp的移动端拉起钱包App,请求支付授权 -> 业务流程图如下: - -![image](http://on-img.com/chart_image/5b659391e4b0f8477da3138b.png?t=1) -``` -// 传递给钱包APP的数据包结构 -{ - protocol string // 协议名,钱包用来区分不同协议,本协议为 SimpleWallet - version string // 协议版本信息,如1.0 - action string // 支付时,赋值为transfer - dappName string // dapp名字,用于在钱包APP中展示,可选 - dappIcon string // dapp图标Url,用于在钱包APP中展示,可选 - from string // 付款人的EOS账号,可选 - to string // 收款人的EOS账号,必须 - amount number // 转账数量,必须 - contract string // 转账的token所属的contract账号名 - symbol string // 转账的token名称,必须 - precision number // 转账的token的精度,小数点后面的位数,必须 - dappData string // 由dapp生成的业务参数信息,需要钱包在转账时附加在memo中发出去,格式为:k1=v1&k2=v2,可选 - // 钱包转账时还可附加ref参数标明来源,如:k1=v1&k2=v2&ref=walletname - desc string // 交易的说明信息,钱包在付款UI展示给用户,最长不要超过128个字节,可选 - callback string // 用户完成操作后,钱包回调拉起dapp移动端的回调URL,如appABC://abc.com?action=login,可选 - // 钱包回调时在此URL后加上操作结果(result、txID),如:appABC://abc.com?action=login&result=1&txID=xxx, - // result的值为:0为用户取消,1为成功, 2为失败;txID为EOS主网上该笔交易的id(若有) -} -``` -- 钱包组装上述数据,生成一笔EOS的transaction,用户授权此笔转账后,提交转账数据到EOS主网;如果有callback,则回调拉起dapp的应用 -- dapp可根据callback里的txID去主网查询此笔交易(不能完全依赖此方式来确认用户的付款);或自行搭建节点监控EOS主网,检查代币是否到账 - - -### 错误处理 -- code不等于0则请求失败 -``` -// 错误返回 -{ - code number //错误符,等于0是成功,大于0说明请求失败,dapp返回具体的错误码 - error string //返回的提示信息 -} -``` - -## FAQ - -* 如何避免用户扫描了伪造的二维码? - - > 虽然可以通过创建一个统一的dapp和钱包注册中心,通过白名单的方式来避免钓鱼,但这会使此协议更复杂、更中心化,从而也更脆弱。我们建议钱包商在界面上提醒用户注意识别二维码的来源,提高用户的安全意识,同时向用户展示签名的原始信息。 - -* 二维码的信息过多,可否增加压缩算法? - - > 我们进行过测试,能压缩20-30%左右,效果不算特别理想,因此协议中没有将压缩算法正式纳入。虽然二维码看起来过密,但钱包基本均可正常识别。我们建议,如果二维码信息过多,dapp在展示二维码的时候,适当加大尺寸,让用户不必将手机凑近屏幕,提高钱包的识别速度。 - -* 在验证登录信息的时候,dapp应该验证active还是owner的签名? - - > 我们建议dapp先验证active的签名,若不通过,再验证owner。对于钱包商来说,建议用active权限来签名。 - -* 对dapp内嵌到钱包里面的场景,SimpleWallet协议为何不制定相关登录和支付标准? - - > 目前多数钱包均在开发或已开发出自己的一套相关标准,统一标准的代价很大。我们建议各钱包商也参考scatter的方案来,这样会大大降低在web端已经接入了scatter的dapp们的适配成本。 - -* SimpleWallet协议为何不制定钱包和dapp之间的智能合约调用的标准? - - > 同上。 - - -## 更新说明 -- 9.6 - 增加了FAQ内容 -- 8.17 - 增加测试链接; - 支付操作中增加了callback参数; - 修改两个字段的命名,expire->expired,callbackUrl->callback -- 8.16 - 修改dapp的应用调用钱包APP时的callback,钱包只需要附加result结果即可,无需拼装action参数 -- 8.15 - 简化协议,取消info字段;增加desc字段,此字段是string类型,用来描述一个交易 +# MATH SimpleWallet Protocol Readme + +Version: 2.0 + +Last updated: 2021.9.7 + +## About + +MATH SimpleWallet is the protocol for connecting native blockchain game mobile app to MathWallet. + +It supports all EVM & Substrate blockchains including Ethereum, Bsc, Polkadot, etc. + +## API + +[English](https://github.com/mathwallet/SimpleWallet/blob/v2/README_en.md) + +[中文](https://github.com/mathwallet/SimpleWallet/blob/v2/README_cn.md) + +## Chain Type & ID + +| Chain Type | Chain ID | Description | +| --- | --- | --- | +| evm | 1 | Ethereum Chain | +| evm | 56 | Binance Smart Chain | +| evm | 128 | Huobi ECO Chain | +| evm | 66 | OKExChain | +| solana | 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d | Solana Mainnet Beta | +| substrate | 0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3 | Polkadot | +| substrate | 0xb0a8d493285c2df73290dfb7e61f870f17b41801197a149ca93654499ea3dafe | Kusama | + +More EVM ChainID can be found: https://chainlist.org/ + +More Substrate Genesis Hash can be found: https://polkadot.js.org/apps/#/settings/metadata + +## SDK & Demo + +iOS SDK +https://github.com/mathwallet/MathWallet5SDK-iOS + +Android SDK +https://github.com/mathwallet/MathWallet5SDK-Android + +## Misc + +This Protocol is more focus on app to app connection. If you are developing a web based dapp, we'd suggest using web3js or walletconnect protocal, details can be found at https://doc.mathwallet.org + +Any questions, feel free to contact labs@mathwallet.org diff --git a/README_cn.md b/README_cn.md new file mode 100644 index 0000000..02aeda4 --- /dev/null +++ b/README_cn.md @@ -0,0 +1,277 @@ +# SimpleWallet 协议文档 + +版本:2.0 + +最后更新:2021.9.7 + +## 简介 +SimpleWallet是一个数字资产钱包和移动应用(如:区块链游戏)的通用对接协议,支持Ethereum等EVM兼容区块链。 + +## SDK & Demo + +iOS SDK +https://github.com/mathwallet/MathWallet5SDK-iOS + +Android SDK +https://github.com/mathwallet/MathWallet5SDK-Android + +## 功能列表 + +- 登录 + +场景:dapp的移动端APP拉起钱包APP,请求登录授权 + + +- 支付 + +场景:dapp的移动端拉起钱包APP请求支付授权 + +- 发送交易体上链 + +场景:dapp的移动端拉起钱包App,执行Transaction调用智能合约接口 + +- 打开 DApp URL + +场景:dapp的移动端拉起钱包App,打开对应DApp URL + +## 协议内容 + +### 1. 钱包APP在系统注册拦截协议 + +钱包APP应在操作系统内注册拦截协议(URL Scheme、appLink),以便dapp的APP拉起钱包应用。 + +以下为协议接入方法: +> mathwallet://mathwallet.org?sw={json数据} + +协议基础结构: + +``` + +// 请求数据包结构 +{ + protocol string // 协议名,钱包用来区分不同协议,本协议为 SimpleWallet + version string // 协议版本信息,如2.0 + chain object // 见下面,公链数据结构 + dapp object // 见下面,dapp 信息数据结构 + id string // dapp生成的,用于作为请求id + action string // 具体操作(如: login\transaction\openURL\signMessage) + data object // 详情见下面场景 + callback string // 用户完成操作后,钱包回调拉起dapp移动端的回调URL,可选 + // 如appABC://abc.com?response={response} + // response 见下面,响应数据包结构 +} + +// 公链数据结构(公链标识表格: https://github.com/mathwallet/SimpleWallet) +{ + type string // 公链类型(如:EVM),必须 + id string // 公链区分id(如:1),必须 +} + +// dapp 信息数据结构 +{ + name string // dapp名字,用于在钱包APP中展示,必须 + icon string // dapp图标Url,用于在钱包APP中展示,可选 +} + + +// 回调数据包结构 +{ + id string // dapp 生成的请求id + code number // 0为用户取消,1为成功, 2为失败 + result Object // 具体数据,见下面使用场景,可选 + message string // 错误信息,可选 +} + +``` + +### 2. 登录 + +#### 场景:dapp的移动端应用拉起钱包App,请求登录授权 + +> 适合dapp的移动端(iOS或安卓端)接入。业务流程图如下: + +![image](http://qiniu.eth.fm/2021-09-03-flow.jpg) + +- dapp的移动端拉起钱包APP要求登录授权,并传递给钱包App如下的数据,数据格式为json: + +``` +// dapp传递给钱包APP的数据包结构 + +{ + ... + "id": "...", + "action": "login", + "data":{} +} +``` + +- 钱包App 响应数据包结构(成功) +``` +// 成功 +{ + "id": "...", + "code": 1, + "result": { + "name": "Ben", // 账户名称 + "address": "0x000000..." // 账户地址 + } +} + +// 取消或错误 +{ + "id": "...", + "code": 0, + "message": "用户取消" +} +``` + +### 3. 支付 + +#### 场景:dapp的移动端拉起钱包App,请求支付授权 + +> 业务流程图如下: + +![image](http://qiniu.eth.fm/2021-09-03-flow.jpg) + +``` +// dapp传递给钱包APP的数据包结构 +// EVM 系 +{ + ... + "id": "...", + "action": "transaction", + "data":{ + "from": "0x00000...", // 付款人的地址,必须 + "to": "0x00000...", // 付款人的地址,必须 + "value": "1000000000000", // 转账数量(1 ETH = 100000000000000000),必须 + "data": "0x", // 可选 + } + ... +} +// SOLANA 系 +{ + ... + "id": "...", + "action": "transaction", + "data":{ + "recentBlockhash": "C3i1dknJJguECL63uNJGXCQdzU9t5fFg7ktdJJfxEfqB", // BlockHash,可选 + "instructions": [ + { + "keys": [ + { + "pubkey":"GNutLCXQEEcmxkJH5f5rw51bTW2QcLGXqitmN3EaVPoV", // An account's public key,必须 + "isSigner": true, // True if an instruction requires a transaction signature matching `pubkey`.必须 + "isWritable": true, // True if the `pubkey` can be loaded as a read-write account.必须 + } + ], + "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // Program Id,必须 + "data": "0x0000000" // Program input,必须 + } + ] + } + ... +} +// 其它公链(待补充) +``` + +- 钱包App 响应数据包结构(成功) +``` +// 成功 +{ + "id": "...", + "code": 1, + "result": { + "hash": "0x000000" + } +} + +// 取消或错误 +{ + "id": "...", + "code": 0, + "message": "用户取消" +} +``` + +- 钱包组装上述数据,生成一笔Ethereum的transaction,用户授权此笔转账后,提交转账数据到Ethereum主网;如果有callback,则回调拉起dapp的应用 +- dapp可根据callback里的txHash去主网查询此笔交易(不能完全依赖此方式来确认用户的付款);或自行搭建节点监控Ethereum(或EOS)主网同步节点,检查代币是否到账 + + +### 4. 消息签名 + +#### 场景:dapp的移动端拉起钱包进行签名 + +``` +// dapp传递给钱包APP的数据包结构 + +{ + ... + "id": "...", + "action": "signMessage", + "data":{ + "address": "0x0000000", // 签名地址 + "message": "hello world", // 签名数据,格式 utf-8、hex(16进制数据必须0x开头),必须 + } + ... +} +``` + +- 钱包App 响应数据包结构(成功) +``` +// 成功 +{ + "id": "...", + "code": 1, + "result": { + "signature": "0x000000" + } +} + +// 取消或错误 +{ + "id": "...", + "code": 0, + "message": "用户取消" +} +``` + +### 5. 打开 DApp URL + +#### 场景:dapp的移动端拉起钱包App,并在钱包App中打开指定 URL + + +``` +// dapp传递给钱包APP的数据包结构 + +{ + ... + "id": "...", + "action": "openURL", + "data":{ + "link": "https://mathwallet.org", // 链接地址,必须 + } + ... +} +``` + +- 钱包App 响应数据包结构(成功) +``` +// 成功 +{ + "id": "...", + "code": 1, + "result": {} +} + +// 取消或错误 +{ + "id": "...", + "code": 0, + "message": "用户取消" +} +``` +- dApp 页面内回调 + +```javascript + window.location.href = "mathwallet5demos://demos.com?success=1&data=666" +``` diff --git a/README_en.md b/README_en.md index d6ae048..95fc11d 100644 --- a/README_en.md +++ b/README_en.md @@ -1,274 +1,250 @@ # SimpleWallet protocol document -Version: 1.0 +Version: 2.0 -Last updated: 2018.8.17 - -Scroll to the end for version updates - -中文版:https://github.com/southex/SimpleWallet/blob/master/README.md +Last updated: 2021.9.3 ## Introduction -SimpleWallet is a universal protocol for connecting EOS wallets and dapp.we +SimpleWallet is a universal protocol for connecting native blockchain game mobile app to MathWallet. -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 mobile dapp. -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. +## SDK & Demo -This protocol has been built to be compatible with several wallets, and is currently undergoing final tests to ensure their compatibility. +iOS SDK +https://github.com/mathwallet/MathWallet5SDK-iOS -Test page link: [http://demo.eossw.io](http://demo.eossw.io/) +Android SDK +https://github.com/mathwallet/MathWallet5SDK-Android ## 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 +- Sign a message +- Open Dapp URL -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) +Scenario: The Mobile App requests payment authorization (Mobile DApp) ## Flow of the Protocol -#### 1. The Wallet App registers the intercept protocol in the system +### 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 +MathWallet 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: mathwallet://mathwallet.org 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: +mathwallet://mathwallet.org?sw={the json data} -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: - -![](https://images-cdn.shimo.im/z5aJ1nw4NnEjGcYQ/image.png!thumbnail) +``` -- 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: +// JSON Data +{ + protocol string // protocol name, wallet is used to distinguish different protocols, and this protocol is SimpleWallet + version string // protocol version information (ex:2.0) + chain object // chain object + dapp object // dapp information + id string // request id + action string // reqeust action, ex: login,transaction,openURL,signMessage + data object // reqeust Data + callback string // after the user completes the operation, the wallet callback pulls up the callback URL of the dapp mobile terminal, optional + // such as appABC://abc.com?response={response} +} -``` -// The QR code data format for login +// Chain Object +// Chain name table:: https://github.com/mathwallet/SimpleWallet { - 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 + type string // chain type(ex:EVM),required + id string // chain id(1),required } -``` -- 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 +// DApp Object { -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 + name string // dapp name for display in the wallet APP + icon string // dapp icon Url for display in the wallet APP } -``` -- 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 + +// Callback { - 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 + id string // request id + code number // The value of result is: 0 for user cancel, 1 for success and 2 for failure + result Object // response data, optional + message string // error message, optional } + ``` -#### 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: +### 2. Login + +#### Scenario: 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 + ... + "id": "...", + "action": "login", + "data":{} } ``` -- 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: - -![](https://i.imgur.com/x8dT0G5.png) +- Response ``` -// the QR code data format generated by dapp for wallet scanning +// Success { -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). + "id": "...", + "code": 1, + "result": { + "name": "Ben", // wallet name + "address": "0x000000..." // wallet address + } +} +// Cancel or Error +{ + "id": "...", + "code": 0, + "message": "Unknown Error" } ``` -- 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 +### 3. Payment -- 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 +#### Scenario: The mobile end of dapp pulls up the wallet App and requests payment authorization Business flow chart is as follows: -![](https://i.imgur.com/co8vhTb.png) +![](http://qiniu.eth.fm/2021-09-03-flow.jpg) The data package structure transfered by dapp to wallet APP ``` +// EVM { -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). - + ... + "id": "...", + "action": "transaction", + "data":{ + "from": "0x00000...", // Address of payer, required + "to": "0x00000...", // Address of recipient, required + "value": "100000000000000", // The amount of transfers(1 ETH = 10000000000000000),required + "data": "0x", // optional + } + ... } -``` -- 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. +// SOLANA +{ + ... + "id": "...", + "action": "transaction", + "data":{ + "recentBlockhash": "C3i1dknJJguECL63uNJGXCQdzU9t5fFg7ktdJJfxEfqB", // BlockHash,optional + "instructions": [ + { + "keys": [ + { + "pubkey":"GNutLCXQEEcmxkJH5f5rw51bTW2QcLGXqitmN3EaVPoV", // An account's public key,required + "isSigner": true, // True if an instruction requires a transaction signature matching `pubkey`,required + "isWritable": true, // True if the `pubkey` can be loaded as a read-write account,required + } + ], + "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // Program Id,required + "data": "0x0000000" // Program input,required + } + ] + } + ... +} +// To be added -## Error Handling +``` -The code does not equal 0, and the request fails +- Response ``` -// error return +// Success { - 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 + "id": "...", + "code": 1, + "result": { + "hash": "0x000000" + } } -``` -## 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 +// Cancel or Error +{ + "id": "...", + "code": 0, + "message": "Unknown Error" +} +``` -**8.15** +- The wallet assembles the above data and generates an transaction. After the user authorizes the transfer, the user submits the transfer data to the blockchain; If there is callback, pulls the dapp application +- The Dapp will either check this transaction from the mainnet according to the txHash 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 blockchain by itself, and check whether the tokens are received -Simplify the protocol and cancel the info field +### 4. Sign a message -Added string type: desc to describe a typical transaction +#### Scenario: The mobile end of dapp pulls up the wallet App and sign a specific message for validation +The data package structure transfered by dapp to wallet APP -## FAQ -- How can I prevent users from scanning fake QR codes? +``` +{ + ... + "id": "...", + "action": "signMessage", + "data":{ + "address": "0x0000000", // address + "message": "hello world", // sign message( utf-8, hex ) + } + ... +} - > 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? +### 5. Open Dapp URL - > 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. +#### Scenario: The mobile end of dapp pulls up the wallet App and open URL inside the wallet in-app browser -- When verifying the login information, should DAPP verify the activity or the signature of the owner? +``` +{ + ... + "id": "...", + "action": "openURL", + "data":{ + "link": "https://mathwallet.org", // link + } + ... +} - > 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. +``` +- Response +``` +// Success +{ + "id": "...", + "code": 1, + "result": { + } +} -- Why doesn't the SimpleWallet protocol set the relevant login and payment standards for the scene in which DAPP is embedded in the wallet? +// Cancel or Error +{ + "id": "...", + "code": 0, + "message": "Unknown Error" +} +``` - > 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. +- Callback used in DAPP -- Why doesn't the SimpleWallet protocol set the standard for smart contract calls between wallet and DAPP? +```javascript + window.location.href = "mathwallet5demos://demos.com?success=1&data=666" +``` - > Ibid. diff --git a/invoke_wallet.png b/invoke_wallet.png deleted file mode 100644 index b653b19..0000000 Binary files a/invoke_wallet.png and /dev/null differ diff --git a/supporter_list.md b/supporter_list.md deleted file mode 100644 index 3c4a61a..0000000 --- a/supporter_list.md +++ /dev/null @@ -1,32 +0,0 @@ -# Protocol Supporters - -接入协议的产品名单 - -Last Update: Aug. 31, 2018 - -Please submit your product info if your product have supproted the SimpleWallet protocol。 -如果你的产品已接入SimpleWallet协议,请填写表单提交给我们,我们会定期整理搜集。 - -https://docs.google.com/forms/d/e/1FAIpQLSciEsvqsbale3-zcmktBB62_RzaNlKRtBHY1pVtDvA6SA8XfA/viewform?usp=sf_link - - -## wallet -- MEET.ONE https://meet.one/ -- MORE WALLET https://more.top/ -- KKWallet https://kkwallet.com/ -- TokenPocket https://www.mytokenpocket.vip/ -- HaloWallet https://wap.halowallet.io/ -- EOS LIVE https://eos.live/ -- 番茄钱包 https://tomatowallet.cn/ -- PocketEOS https://pocketeos.com/#/ -- 麦子钱包 http://www.medishares.org/wallet/cn/ - -## exchange - -- SouthEX https://www.southex.com -- Newdex https://newdex.io/ - -## dapp - -- 企鹅大陆 https://www.qiedalu.com/ -- LuckChain http://luckchain.org/