diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..4eeafeb --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +# To get started with Dependabot version updates, you'll need to specify which +# package ecosystems to update and where the package manifests are located. +# Please see the documentation for all configuration options: +# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates + +version: 2 +updates: + - package-ecosystem: "" # See documentation for possible values + directory: "/" # Location of package manifests + schedule: + interval: "daily" diff --git a/README.md b/README.md index fbc6fc7..cff6267 100644 --- a/README.md +++ b/README.md @@ -2,25 +2,10 @@ 版本：1.0 -协议最后更新：2018.8.31 - -English Version: https://github.com/southex/SimpleWallet/blob/master/README_en.md （ EOSShenzhen 翻译） +协议最后更新：2019.01.04 ## 简介 -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接入此协议，并向我们提交你们的产品信息。 +SimpleWallet是一个数字资产钱包和dapp的通用对接协议，支持Ethereum、EOS、EOS Force、TRON。 ## 功能列表 - 登录 @@ -33,21 +18,24 @@ SimpleWallet是一个EOS钱包和dapp的通用对接协议。 2. 场景2：dapp的移动端拉起钱包APP请求支付授权 3. 场景3：钱包APP内嵌dapp的H5页面，进行支付（暂无） +- 交易体 +1. 场景1：钱包扫描二维码，执行Transaction +2. 场景2：dapp的移动端拉起钱包App，执行Transaction + +- 打开 DApp URL +1. 场景1：dapp的移动端拉起钱包App，打开对应DApp URL + ## 协议内容 ### 1. 钱包APP在系统注册拦截协议 钱包APP应在操作系统内注册拦截协议（URL Scheme、appLink），以便dapp的APP拉起钱包应用。 -以下为安卓端的协议接入方法： - -拦截协议为：simplewallet://eos.io - -dapp的移动端应用可以调用此协议，传递数据给钱包APP，传递数据的请求格式为： +以下为协议接入方法： +> mathwallet://mathwallet.org?param={json数据} -simplewallet://eos.io?param={json数据} - -对于iOS端，由于其app之间的调用机制和安卓差别很大，制定统一的协议非常复杂，且目前基于iOS的dapp和钱包很少，因此SimpleWallet不对iOS上进行协议统一。各方钱包和dapp可自行协商对接方法。 +兼容之前的SimpleWallet协议 +> simplewallet://eos.io?param={json数据} ### 2. 登录 @@ -65,12 +53,13 @@ simplewallet://eos.io?param={json数据} { protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet version string // 协议版本信息，如1.0 + blockchain string // 公链标识（eosio、eosforce、ethereum,tron等） dappName string // dapp名字 dappIcon string // dapp图标 action string // 赋值为login uuID string // dapp server生成的，用于此次登录验证的唯一标识 loginUrl string // dapp server上用于接受登录验证信息的url - expired number // 二维码过期时间，unix时间戳 + expired number // 二维码过期时间，unix时间戳 loginMemo string // 登录备注信息，钱包用来展示，可选 } ``` @@ -86,10 +75,11 @@ sign = ecc.sign(data, privateKey) { protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet version string // 协议版本信息，如1.0 + blockchain string // 公链标识（eosio、eosforce、ethereum,tron等） timestamp number // 当前UNIX时间戳 - sign string // eos签名 + sign string // eos、ethereum签名 uuID string // dapp server生成的，用于此次登录验证的唯一标识 - account string // eos账户名 + account string // eos账户名、ethereum地址等 ref string // 来源,如钱包名 } ``` @@ -113,11 +103,13 @@ sign = ecc.sign(data, privateKey) { protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet version string // 协议版本信息，如1.0 + blockchain string // 公链标识（eosio、eosforce、ethereum等） dappName string // dapp名字，用于在钱包APP中展示 dappIcon string // dapp图标Url，用于在钱包APP中展示 action string // 赋值为login uuID string // dapp生成的，用于dapp登录验证唯一标识 loginUrl string // dapp server生成的，用于接受此次登录验证的URL + expired number // 登录过期时间，unix时间戳 loginMemo string // 登录的备注信息，钱包用来展示，可选 callback string // 用户完成操作后，钱包回调拉起dapp移动端的回调URL,如appABC://abc.com?action=login，可选 // 钱包回调时在此URL后加上操作结果(&result)，如：appABC://abc.com?action=login&result=1, @@ -136,29 +128,31 @@ sign = ecc.sign(data, privateKey) // dapp生成的用于钱包扫描的二维码数据格式 { protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet - version string // 协议版本信息，如1.0 + version string // 协议版本信息，如1.0 + blockchain string // 公链标识（eosio、eosforce、ethereum等） dappName string // dapp名字，用于在钱包APP中展示，可选 - dappIcon string // dapp图标Url，用于在钱包APP中展示，可选 + dappIcon string // dapp图标Url，用于在钱包APP中展示，可选 action string // 支付时，赋值为transfer，必须 - from string // 付款人的EOS账号，可选 - to string // 收款人的EOS账号，必须 - amount number // 转账数量，必须 - contract string // 转账的token所属的contract账号名，必须 + from string // 付款人的EOS账号、EOSForce账号或Ethereum地址，可选 + to string // 收款人的EOS账号、EOSForce账号或Ethereum地址，必须 + amount number // 转账数量(带精度，如1.0000 EOS)，必须 + contract string // 转账的token所属的contract账号名或地址，必须 symbol string // 转账的token名称，必须 precision number // 转账的token的精度，小数点后面的位数，必须 - dappData string // 由dapp生成的业务参数信息，需要钱包在转账时附加在memo中发出去，格式为:k1=v1&k2=v2，可选 + dappData string // 由dapp生成的业务参数信息，需要钱包在转账时附加在memo或data中发出去，格式为:k1=v1&k2=v2，可选 // 钱包转账时还可附加ref参数标明来源，如：k1=v1&k2=v2&ref=walletname desc string // 交易的说明信息，钱包在付款UI展示给用户，最长不要超过128个字节，可选 - expired number // 二维码过期时间，unix时间戳 + 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（若有） + // result的值为：0为用户取消，1为成功, 2为失败；txID为EOS、EOS原力或以太坊主网上该笔交易的id（若有） } ``` -- 钱包组装上述数据，生成一笔EOS的transaction，用户授权此笔转账后，提交转账数据到EOS主网；若有callback参数，则进行回调访问 -- dapp可根据callback中的txID去主网查询此笔交易（不能完全依赖此方式来确认用户的付款）；或dapp自行搭建节点监控EOS主网，检查代币是否到账 +- 钱包组装上述数据，生成一笔EOS或Ethereum的transaction，用户授权此笔转账后，提交转账数据到EOS或Ethereum主网；若有callback参数，则进行回调访问 +- dapp可根据callback中的txID去主网查询此笔交易（不能完全依赖此方式来确认用户的付款）；或dapp自行搭建节点监控EOS、EOS原力或Ethereum主网，检查代币是否到账 - 对于流行币种如IQ，如果二维码中给出的contract名和官方的合约名不一致，钱包方要提醒用户，做二次确认 - 钱包应该提醒用户注意辨别二维码的来源，避免被钓鱼攻击 +- TRON钱包支付，请查看协议第4部分（交易体）封装 #### 场景2：dapp的移动端拉起钱包App，请求支付授权 @@ -170,68 +164,238 @@ sign = ecc.sign(data, privateKey) { protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet version string // 协议版本信息，如1.0 + blockchain string // 公链标识（eosio、ethereum、eosforce等） action string // 支付时，赋值为transfer dappName string // dapp名字，用于在钱包APP中展示，可选 - dappIcon string // dapp图标Url，用于在钱包APP中展示，可选 - from string // 付款人的EOS账号，可选 - to string // 收款人的EOS账号，必须 - amount number // 转账数量，必须 - contract string // 转账的token所属的contract账号名 + dappIcon string // dapp图标Url，用于在钱包APP中展示，可选 + from string // 付款人的EOS账号或Ethereum地址，可选 + to string // 收款人的EOS账号或Ethereum地址，必须 + amount number // 转账数量(带精度，如1.0000 EOS)，必须 + contract string // 转账的token所属的contract账号名或地址 symbol string // 转账的token名称，必须 precision number // 转账的token的精度，小数点后面的位数，必须 - dappData string // 由dapp生成的业务参数信息，需要钱包在转账时附加在memo中发出去，格式为:k1=v1&k2=v2，可选 + dappData string // 由dapp生成的业务参数信息，需要钱包在转账时附加在memo或data中发出去，格式为: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, + desc string // 交易的说明信息，钱包在付款UI展示给用户，最长不要超过128个字节，可选 + expired number // 交易过期时间，unix时间戳 + callback string // 用户完成操作后，钱包回调拉起dapp移动端的回调URL,如appABC://abc.com?action=transfer，可选 + // 钱包回调时在此URL后加上操作结果(result、txID)，如：appABC://abc.com?action=transfer&result=1&txID=xxx, // result的值为：0为用户取消，1为成功, 2为失败；txID为EOS主网上该笔交易的id（若有） } ``` -- 钱包组装上述数据，生成一笔EOS的transaction，用户授权此笔转账后，提交转账数据到EOS主网；如果有callback，则回调拉起dapp的应用 -- dapp可根据callback里的txID去主网查询此笔交易（不能完全依赖此方式来确认用户的付款）；或自行搭建节点监控EOS主网，检查代币是否到账 +- 钱包组装上述数据，生成一笔EOS或Ethereum的transaction，用户授权此笔转账后，提交转账数据到EOS或Ethereum主网；如果有callback，则回调拉起dapp的应用 +- dapp可根据callback里的txID去主网查询此笔交易（不能完全依赖此方式来确认用户的付款）；或自行搭建节点监控EOS或Ethereum主网，检查代币是否到账 +- TRON支付，请查看协议第4部分（交易体）封装 +### 4. 交易体 +#### 场景1：钱包扫描二维码，执行Transaction -### 错误处理 -- code不等于0则请求失败 -``` -// 错误返回 +> Ethereum + 参考支付场景，dappData用来存放交易的Data数据。 + +> EOS、EOS原力 + ``` +// 传递给钱包APP的数据包结构 { - code number //错误符，等于0是成功，大于0说明请求失败，dapp返回具体的错误码 - error string //返回的提示信息 + protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet + version string // 协议版本信息，如1.0 + blockchain string // 公链标识（eosio、ethereum、eosforce、tron等） + action string // 支付时，赋值为transaction + dappName string // dapp名字，用于在钱包APP中展示，可选 + dappIcon string // dapp图标Url，用于在钱包APP中展示，可选 + actions string // JSON 数组，格式：[{"code": "eosio.token","action": "transfer","binargs":"00000"}] + from string // 要执行交易的账户，可选 + desc string // 交易的说明信息，钱包在付款UI展示给用户，最长不要超过128个字节，可选 + expired number // 交易过期时间，unix时间戳 + callback string // 用户完成操作后，钱包回调拉起dapp移动端的回调URL, + // 如https://abc.com?action=transaction&qrcID=123，可选 + // 钱包回调时在此URL后加上操作结果(result、txID)， + // 如：https://abc.com?action=transaction&qrcID=123&result=1&txID=xxx, + // result的值为：0为用户取消，1为成功, 2为失败；txID为EOS主网上该笔交易的id（若有） } + ``` +#### 场景2：dapp的移动端拉起钱包App，执行Transaction -## FAQ +> Ethereum(以太坊) -* 如何避免用户扫描了伪造的二维码？ + 参考支付场景，dappData用来存放交易的Data数据。 + +> EOS主网、EOS原力 - > 虽然可以通过创建一个统一的dapp和钱包注册中心，通过白名单的方式来避免钓鱼，但这会使此协议更复杂、更中心化，从而也更脆弱。我们建议钱包商在界面上提醒用户注意识别二维码的来源，提高用户的安全意识，同时向用户展示签名的原始信息。 + ``` +// 传递给钱包APP的数据包结构 +{ + protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet + version string // 协议版本信息，如1.0 + blockchain string // 公链标识（eosio、eosforce） + action string // 支付时，赋值为transaction + dappName string // dapp名字，用于在钱包APP中展示，可选 + dappIcon string // dapp图标Url，用于在钱包APP中展示，可选 + actions string // JSON 数组，格式：[{"code": "eosio.token","action": "transfer","binargs":"00000"}] + from string // 要执行交易的账户，可选 + desc string // 交易的说明信息，钱包在付款UI展示给用户，最长不要超过128个字节，可选 + expired number // 交易过期时间，unix时间戳 + callback string // 用户完成操作后，钱包回调拉起dapp移动端的回调URL, + // 如appABC://abc.com?action=transfer， + // 可选钱包回调时在此URL后加上操作结果(result、txID)， + // 如：appABC://abc.com?action=transaction&result=1&txID=xxx, + // result的值为：0为用户取消，1为成功, 2为失败；txID为EOS主网上该笔交易的id（若有） +} -* 二维码的信息过多，可否增加压缩算法？ +``` - > 我们进行过测试，能压缩20-30%左右，效果不算特别理想，因此协议中没有将压缩算法正式纳入。虽然二维码看起来过密，但钱包基本均可正常识别。我们建议，如果二维码信息过多，dapp在展示二维码的时候，适当加大尺寸，让用户不必将手机凑近屏幕，提高钱包的识别速度。 +> TRON(波场) -* 在验证登录信息的时候，dapp应该验证active还是owner的签名？ + ``` +// 传递给钱包APP的数据包结构 +{ + protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet + version string // 协议版本信息，如1.0 + blockchain string // 公链标识（tron） + action string // 调用时，赋值为transaction + dappName string // dapp名字，用于在钱包APP中展示，可选 + dappIcon string // dapp图标Url，用于在钱包APP中展示，可选 + contract string // JSON 数组，格式参考下面说明； + from string // 要执行交易的账户，可选 + desc string // 交易的说明信息，钱包在付款UI展示给用户，最长不要超过128个字节，可选 + expired number // 交易过期时间，unix时间戳 + callback string // 用户完成操作后，钱包回调拉起dapp移动端的回调URL, + // 如appABC://abc.com?action=transfer， + // 可选钱包回调时在此URL后加上操作结果(result、txID)， + // 如：appABC://abc.com?action=transaction&result=1&txID=xxx, + // result的值为：0为用户取消，1为成功, 2为失败；txID为TRON主网上该笔交易的id（若有） +} +``` - > 我们建议dapp先验证active的签名，若不通过，再验证owner。对于钱包商来说，建议用active权限来签名。 +// 传递给钱包APP的contract字段说明 +1. TriggerSmartContract +``` +[{ + "parameter": { + "value": { + "data": "7365870b0000000000000000000000000000000000000000000000000000000000000060", + "owner_address": "TWXNtL6rHGyk2xeVR3QqEN9QGKfgyRTeU2", + "contract_address": "TWXNtL6rHGyk2xeVR3QqEN9QGKfgyRTeU2", + "call_value": 10000000 + }, + "type_url": "type.googleapis.com/protocol.TriggerSmartContract" + }, + "type": "TriggerSmartContract" +}] +``` -* 对dapp内嵌到钱包里面的场景，SimpleWallet协议为何不制定相关登录和支付标准？ +2. TransferAssetContract +``` +[{ + "parameter": { + "value": { + "amount": 2, + "asset_name": "tokenId", // asset_name对应的值为tokenId + "owner_address": "TWXNtL6rHGyk2xeVR3QqEN9QGKfgyRTeU2", + "to_address": "TWXNtL6rHGyk2xeVR3QqEN9QGKfgyRTeU2" + }, + "type_url": "type.googleapis.com/protocol.TransferAssetContract" + }, + "type": "TransferAssetContract" +}] +``` + +3. TransferContract +``` +[{ + "parameter": { + "value": { + "amount": 8, + "owner_address": "TWXNtL6rHGyk2xeVR3QqEN9QGKfgyRTeU2", + "to_address": "TWXNtL6rHGyk2xeVR3QqEN9QGKfgyRTeU2" + }, + "type_url": "type.googleapis.com/protocol.TransferContract" + }, + "type": "TransferContract" +}] +``` +### 5. 消息签名 +#### 场景1：扫描二维码进行签名 + ``` +// 传递给钱包APP的数据包结构 +{ + protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet + version string // 协议版本信息，如1.0 + blockchain string // 公链标识（eosio、ethereum、eosforce、tron等） + action string // 跳转时，赋值为signMessage + dappName string // dapp名字，用于在钱包APP中展示，可选 + dappIcon string // dapp图标Url，用于在钱包APP中展示，可选 + desc string // 跳转的说明信息，钱包在付款UI展示给用户，最长不要超过128个字节，可选 + message string // 要签名的数据 + isHex bool // 是否是16进制数据 + callback string // 用户完成操作后，钱包回调拉起dapp移动端的回调URL, + // 如https://abc.com?action=signMessage，可选 + // 钱包回调时在此URL后加上操作结果(signedMessage)， + // 如：https://abc.com?action=signMessage&result=1&account=xxx&pubKey=xxx&signedMessage=xxx, + // result的值为：0为用户取消，1为成功, 2为失败；signedMessage被签名后的数据 +} + ``` + +#### 场景2：dapp的移动端拉起钱包进行签名 + ``` +// 传递给钱包APP的数据包结构 +{ + protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet + version string // 协议版本信息，如1.0 + blockchain string // 公链标识（eosio、ethereum、eosforce、tron等） + action string // 跳转时，赋值为signMessage + dappName string // dapp名字，用于在钱包APP中展示，可选 + dappIcon string // dapp图标Url，用于在钱包APP中展示，可选 + desc string // 跳转的说明信息，钱包在付款UI展示给用户，最长不要超过128个字节，可选 + message string // 要签名的数据 + isHex bool // 是否是16进制数据 + callback string // 用户完成操作后，钱包回调拉起dapp移动端的回调URL, + // 可选,如appABC://abc.com?action=signMessage， + // 钱包回调时在此URL后加上操作结果(result)， + // 如：appABC://abc.com?action=signMessage&result=1&account=xxx&pubKey=xxx&signedMessage=xxx + //result的值为：0为用户取消，1为成功, 2为失败；signedMessage被签名后的数据 +} + +``` - > 目前多数钱包均在开发或已开发出自己的一套相关标准，统一标准的代价很大。我们建议各钱包商也参考scatter的方案来，这样会大大降低在web端已经接入了scatter的dapp们的适配成本。 +### 6. 打开 DApp URL +#### 场景1：dapp的移动端拉起钱包App，打开对应DApp URL -* SimpleWallet协议为何不制定钱包和dapp之间的智能合约调用的标准？ + ``` +// 传递给钱包APP的数据包结构 +{ + protocol string // 协议名，钱包用来区分不同协议，本协议为 SimpleWallet + version string // 协议版本信息，如1.0 + blockchain string // 公链标识（eosio、ethereum、eosforce、tron等） + action string // 跳转时，赋值为openUrl + dappName string // dapp名字，用于在钱包APP中展示，可选 + dappIcon string // dapp图标Url，用于在钱包APP中展示，可选 + desc string // 跳转的说明信息，钱包在付款UI展示给用户，最长不要超过128个字节，可选 + dappUrl string // 要跳转的DApp URL链接 + callback string // 用户完成操作后，钱包回调拉起dapp移动端的回调URL, + // 可选,如appABC://abc.com?action=openUrl， + // 钱包回调时在此URL后加上操作结果(result)， + // 如：appABC://abc.com?action=openUrl&result=0, + // result的值为：0为用户取消, 2为失败；成功不回调； + // 该回调只会在打开URL失败或取消时触发 +} - > 同上。 +``` +### 网络回调接口错误处理 +- code不等于0则请求失败 +``` +// 错误返回 +{ + code number //错误符，等于0是成功，大于0说明请求失败，dapp返回具体的错误码 + error string //返回的提示信息 +} +``` -## 更新说明 -- 9.6 - 增加了FAQ内容 -- 8.17 - 增加测试链接； - 支付操作中增加了callback参数； - 修改两个字段的命名，expire->expired,callbackUrl->callback -- 8.16 - 修改dapp的应用调用钱包APP时的callback，钱包只需要附加result结果即可，无需拼装action参数 -- 8.15 - 简化协议，取消info字段；增加desc字段，此字段是string类型，用来描述一个交易 +### 麦子钱包DApp跳转错误处理 +- result不等与1 表示取消或失败 +``` +// 错误返回 +errorMesssge string //返回的提示信息 +``` diff --git a/math_qrcode_document.md b/math_qrcode_document.md new file mode 100644 index 0000000..811db0d --- /dev/null +++ b/math_qrcode_document.md @@ -0,0 +1,19 @@ +## Math Wallet QRCode 文档 + +转账 +~~~ +{ + "client": "MathWallet", + "type": "EOS", + "action": "transfer", + "data": { + "to": "bigbigbigbig", + "amount": "1.0000 EOS", + "precision": 4, + "contract": "eosio.token", + "memo":"memo" + } +} +~~~ + +* 使用 SimpleWallet 协议，可参考 https://github.com/MediShares/SimpleWallet/blob/master/README.md