Introducing the WalletsNet CLI

 

开发者接入 WalletsNet 经常会问到两个问题：

• 如何加解密消息？
• 如何在本地开发？本地开发面临的一个挑战是如何「收」消息

我们今天介绍的 CLI 工具就是为了解决这两个问题，我们开始吧。

 

第一步，启动 ngrok

本地开发的 server 如何收到来自 WalletsNet 的消息推送呢？其实原理就是建立一个通讯的 tunnel，业界有很多第三方的工具，我们这里选择了最流行的工具 —— ngrok（关于ngrok的介绍，可以看它的官网：https://ngrok.com）

首先注册一个 ngrok 的账户，然后就可以下载它的客户端了，在本地启动客户端，非常简单，像这样：

xxxxxxxxxx
14
1
./ngrok http https://localhost:12222
2

3
ngrok by @inconshreveable                                                                                                                                                                   (Ctrl+C to quit)
4
                                                                                                                                                                                                            
5
Session Status                online                                                                                                                                                                        
6
Account                       ****** (Plan: Free)                                                                                                                                                         
7
Version                       2.3.40                                                                                                                                                                        
8
Region                        United States (us)                                                                                                                                                            
9
Web Interface                 http://127.0.0.1:4040                                                                                                                                                         
10
Forwarding                    http://cd49-222-128-202-xxx.ngrok.io -> https://localhost:12222                                                                                                                
11
Forwarding                    https://cd49-222-128-202-xxx.ngrok.io -> https://localhost:12222                                                                                                               
12
                                                                                                                                                                                                            
13
Connections                   ttl     opn     rt1     rt5     p50     p90                                                                                                                                   
14
                              0       0       0.00    0.00    0.00    0.00

如此一来你就得到了一个公网的域名临时域名（当然，如果你付费了，就可以设置固定的域名，否则每次重启 ngrok 都会随机重新分配） —— http://cd49-222-128-202-xxx.ngrok.io，这个域名收到的所有消息，都会被转发至你本地的 https://localhost:12222 （至于为什么是12222这个端口呢？一会儿会提到）。

然后，将 ngrok 提供的这个域名配置到 WalletsNet Dashboard 的 webhook 上面，以后，WalletsNet 就会把消息发送到这里，于是你的本地就能收到了。

ngrok 还提供了一个本地的 web 界面供查看收到的数据：http://127.0.0.1:4040

第二步，安装 CLI

注意：运行 WalletsNet CLI 需要 python 3.8 以上

xxxxxxxxxx
4
1
git clone https://github.com/WalletsClub/cli.git
2
cd cli
3
pip3 install -r requirements.txt
4
pip3 install --editable .

执行完这些指令之后，之后就可以直接使用 walletsnet 这个命令了，CLI 工具支持以下几个命令：

• listen：即在本地启动一个「收发器」
• examples：显示 CLI 支持向 WalletsNet 发送的指令
• trigger：触发执行一个 example
• open：打开 WalletsNet 的 Dashboard、文档等页面
• status：查看 WalletsNet 的状态
• help：帮助

第三步，启动本地收发器

• 从 WalletsNet 的 Dashboard 上面下载配置文件（路径：侧边导航/Transceiver/右上角 Download transceiver configure file）
• 打开下载的配置文件 setting.json，配置好私钥
• 将 setting.json 放置在cli根目录下，然后就可以启动本地收发器了，命令如下：

xxxxxxxxxx
1
1
walletsnet listen --host='localhost' --forward_to='https://localhost:15555'

这局命令的含义是在本地（localhost）启动一个收发器，端口为默认（默认12222），如果forward_to参数被指定了（如上），那么收发器收到消息后将会把消息（解密后明文）转发至本地 https://localhost:15555，这个15555端口的server就是开发者自己开发的用来处理报文的代码。所以，收报文的实际链路为：

xxxxxxxxxx
1
1
WalletsNet -------> ngrok -------> localhost:12222 -------> localhost:15555

注意：虽然 WalletsNet 发送至 ngrok 的数据为加密数据，但是只要获得了 WalletsNet 的公钥，消息还是能够被解密出来的，所以开发者只可将 ngrok 使用在本地开发调试的场景下，千万不可用作实际生产！

收发器如果正确启动，则可以看到下面的输出：

xxxxxxxxxx
16
1
2021-12-21 16:35:14,191 - root - INFO - 
2
'##:::::'##::::'###::::'##:::::::'##:::::::'########:'########::'######::'##::: ##:'########:'########::::::
3
 ##:'##: ##:::'## ##::: ##::::::: ##::::::: ##.....::... ##..::'##... ##: ###:: ##: ##.....::... ##..:::::::
4
 ##: ##: ##::'##:. ##:: ##::::::: ##::::::: ##:::::::::: ##:::: ##:::..:: ####: ##: ##:::::::::: ##:::::::::
5
 ##: ##: ##:'##:::. ##: ##::::::: ##::::::: ######:::::: ##::::. ######:: ## ## ##: ######:::::: ##:::::::::
6
 ##: ##: ##: #########: ##::::::: ##::::::: ##...::::::: ##:::::..... ##: ##. ####: ##...::::::: ##:::::::::
7
 ##: ##: ##: ##.... ##: ##::::::: ##::::::: ##:::::::::: ##::::'##::: ##: ##:. ###: ##:::::::::: ##::::'###:
8
. ###. ###:: ##:::: ##: ########: ########: ########:::: ##::::. ######:: ##::. ##: ########:::: ##:::: ###:
9
:...::...:::..:::::..::........::........::........:::::..::::::......:::..::::..::........:::::..:::::...::
10

11
 * WARNING: This is a development server. Do not use it in a production deployment.
12

13
 * Serving Flask app 'transceiver' (lazy loading)
14
 * Environment: development
15
 * Debug mode: on
16
2021-12-21 16:35:14,451 - werkzeug - INFO -  * Running on https://localhost:12222/ (Press CTRL+C to quit)

 

第四步，查看可以运行哪些sample

打开一个新的terminal，输入命令：walletsnet examples 即可看到我们提供了哪些sample

xxxxxxxxxx
9
1
walletsnet examples
2

3
List of available samples:
4

5
1. Credit transfer
6
Command: walletsnet trigger --example="credit transfer"
7

8
2. Request to Pay
9
Command: walletsnet trigger --example="request to pay"

 

第五步，运行 sample

在运行 sample 之前，别忘了有几件事情要完成：

• 在 WalletsNet 的 Dashboard 上面完成与「模拟器对手方」的 Connection
• 在本地的15555端口启动一个服务，接受来自收发器解密后的数据，可以display出来看一下

假设我们发送一笔 credit transfer 交易指令给 WalletsNet：

xxxxxxxxxx
6
1
walletsnet trigger --example="credit transfer"
2

3
2021-12-21 17:01:44,181 - urllib3.connectionpool - DEBUG - Starting new HTTPS connection (1): sandbox.walletsnet.com:443
4
2021-12-21 17:01:44,351 - urllib3.connectionpool - DEBUG - https://sandbox.walletsnet.com:443 "POST /messages HTTP/1.1" 200 45
5
2021-12-21 17:01:44,357 - root - INFO - [√] XPAY --> WalletsNet: pacs.008 message send successful!
6
[√] Trigger succeeded! Check dashboard for transaction details.

这条指令会转发给模拟器对手方，模拟器收到消息后会无条件的接受你的交易，然后你就可以看到本地收发器收到了消息，是这样的：

xxxxxxxxxx
5
1
// 以下是收发器收到的消息
2
2021-12-21 17:04:28,947 - transceiver - DEBUG - method=POST path=/ status=200 duration=0.1 time=2021-12-21T17:04:28+08:00 ip=116.62.41.74 params=eyJhbGciOiJSUzI1NiIsImtpZCI6ImhZVndtUXJUUTg3UWRHd0s0In0.eyJBcHBIZHIiOiB7IkZyIjogeyJGSUlkIjogeyJGaW5JbnN0bklkIjogeyJDbHJTeXNNbWJJZCI6IHsiTW1iSWQiOiAiV0NTTUhLSEtYWFgifX19fSwgIlRvIjogeyJGSUlkIjogeyJGaW5JbnN0bklkIjogeyJDbHJTeXNNbWJJZCI6IHsiTW1iSWQiOiAiWFBBWUhLSEhYWFgifX19fSwgIkJpek1zZ0lkciI6ICJCMjAyMTEyMjFXQ1NNSEtIS1hYWEJQU1AxMjE4NjcwNjk3MSIsICJNc2dEZWZJZHIiOiAicGFjcy4wMDIuMDAxLjExIiwgIkNyZUR0IjogIjIwMjEtMTItMjEifSwgIkRvY3VtZW50IjogeyJGSVRvRklQbXRTdHNScHQiOiB7IkdycEhkciI6IHsiQ3JlRHRUbSI6ICIyMDIxLTEyLTIxIDE3OjA0OjI3Ljg1ODI3NiswODowMCIsICJNc2dJZCI6ICJCMjAyMTEyMjFXQ1NNSEtIS1hYWEJQU1AxMjE4NjcwNjk3MSJ9LCAiT3JnbmxHcnBJbmZBbmRTdHMiOiB7Ik9yZ25sQ3JlRHRUbSI6ICIyMDIxLTEyLTIxVDE3OjA0OjI3LjE1NDg5NyswODowMCIsICJPcmdubE1zZ0lkIjogIkIyMDIxMTIyMVhQQVlIS0hIWFhYQlBTUDI1OTk3NDE2ODg4IiwgIk9yZ25sTXNnTm1JZCI6ICJwYWNzLjAwOC4wMDEuMDkiLCAiT3JnbmxOYk9mVHhzIjogMX0sICJUeEluZkFuZFN0cyI6IHsiQWNjcHRuY0R0VG0iOiAiMjAyMS0xMi0yMSAxNzowNDoyNy44NTgyNzYrMDg6MDAiLCAiSW5zdGRBZ3QiOiB7IkZpbkluc3RuSWQiOiB7IkNsclN5c01tYklkIjogeyJNbWJJZCI6ICJYUEFZSEtISFhYWCJ9fX0sICJJbnN0Z0FndCI6IHsiRmluSW5zdG5JZCI6IHsiQ2xyU3lzTW1iSWQiOiB7Ik1tYklkIjogIldDU01IS0hLWFhYIn19fSwgIk9yZ25sSW5zdHJJZCI6ICIyMDIxMTIyMVhQQVlIS0hIWFhYQldQU1AzODIyNzI4NTY4OCIsICJUeFN0cyI6ICJSQ1ZEIiwgIlN0c1JzbkluZiI6IG51bGx9fX19.iCcT57kTIny89RZ_WsU4S6TXKenG0oe0AgPXhiIW551CWlwNybzANe5zMxXOPw439TsRHtPVekkGWIhDXM9Ve3p-hyMIiI8gs6gj6oZXSzFHN0h9fCCXYEnm_ouJ6p9rUSmqKtlahlVcPUq-iOK4zEfK4hCT7n4bjO2_78lNTDhSH7ZLB21cv6mAM3nnLDngHXzFSWquvudYVD2JRLwqU7QvtofHoFNDME73_GQ3LXbSF78vn0_M65Q-gZnDTJXyN5O_afgk0ghJ1vN0tIoprWTFk89KpuwDoEHKxMQZz3leSp9Z3VGwbw4a6UJPuQh4zkbzvGEmAeCGX5MeBXqL9Q
3

4
// 收发器收到消息并解密后，转发给开发者本地服务器
5
2021-12-21 17:04:28,946 - urllib3.connectionpool - DEBUG - https://localhost:15555 "POST / HTTP/1.1" 200 24

本文中，我们在15555端口随便起了一个服务，用来接收数据并display一下流程，此时便看到了这样的输出：

（P.S. 如果你连“随便起个服务”都不想搞，也没关系，我们在这里为你准备好了这个“随便起的服务”：https://github.com/WalletsClub/simple-processor）

xxxxxxxxxx
9
1
127.0.0.1 - - [18/Dec/2021 19:25:14] "POST / HTTP/1.1" 200 -
2
-----> My server receive message: (pacs.002)
3
... // 这里是print出来的消息，太长了，省略
4
-----> Processing...
5
----------------------------------------------------------------------------------------------------
6
[√] Credit transfer succeeded, e2e transaction ID is: 20211221XPAYHKHHXXXBWPSP38227285688
7
Debit/Credit your user's account here...
8
----------------------------------------------------------------------------------------------------
9
-----> Done

说明，我们发出去的 pacs.008 已经被正常的处理了，WalletsNet 返回了 Positive 的 pacs.002，我们就可以 立刻 debit 付款人的账户啦！

完结

几点需要说明的地方，开发者不是必须按照这个流程开发，CLI 工具也不是必须的：

1. 假设开发者能够在一个公网环境的服务器上开发，则完全不需要使用CLI。但是如果希望本地开发和调试，则CLI会帮助你省去很多麻烦
2. 假设开发者自己通过看 WalletsNet 的文档会自己加解密、收发消息、组装消息，那么也完全不需要用CLI
3. CLI 工具内置的收发器不可用作生产环境，只能用作集成和调试使用
4. ngrok 在某些网络环境下不是很稳定，收不到消息也比较常见（可不是因为 WalletsNet 出问题了哦），多发几次就行了