LWS 接口说明文档
LWS(Light wallet service)是可扩展的轻钱包服务平台,作为BigBang核心网络和IOT 设备的中间服务层, 为运行 LWC 的 IOT 设备提供 BigBang 网络接入,实现设备自身交易数据同步和交易发送。
IOT 设备网络在应用上具备低带宽、高并发等特点,业务和设备条件又对响应延迟和功耗有相当苛刻的 要求。传统互联网技术侧重稳定性、安全性以及人机交互体验等方面的改善;对于 IOT 应用一方面占用 了过多冗余带宽资源,另一方面也难以支撑海量设备接入和高并发低延迟应用。
针对 IOT 应用,目前包括 MQTT、COAP、AMQP 和 DDS 等多种 IOT 网络协议受到众多专业 IOT 企业 支持。Amazon、IBM、阿里云、腾讯云等网络服务商开始提供 IOT 设备数据接入服务,这些专业数据 平台提供 MQTT、COAP 协议接口实现 IOT 设备接入、设备认证、资源管理等服务,同时通过 TLS 安全 协议保证链路数据安全。
LWS 和 IOT 设备之间通信以 MQTT 协议作为底层传输协议,本文档描述对 MQTT 传输配置要求和应用 层协议规范。
符合 MQTT v3.1.1 协议规范,具体配置遵循以下要求:
-
Service Request设置QoS为QoS0;其它命令设置为QoS1,最大重发次数为3;
-
消息长度不大于 500B;
-
LWS、LWC约定MQTT主题(Topic)格式为:
{$LWS-ID}/lws/{$FUNCTION}
{$LWC-ID}/lwc/{$FUNCTION}
-
Payload 中数值变量按 little endian 存放。
-
Service Request/Reply
- Service Request
主题(Topic): {$LWS-ID}/lws/ServiceReq 调用方式: LWC → LWS 描述: LWC上线后服务请求Payload：
Name Description Bytes Nonce 非重复事务 ID ,由 LWC 分配非 0 唯一 ID 2 Address LWC 地址 33 Version LWC 协议版本号 4 TimeStamp Unix timestamp 4 ForkNum 请求分支列表数量,最大不超过64 1 ForkList 请求分支 ID 列表 32*ForkNum ReplyUTXO 后续 SyncReply和UTXOUpdate命令中UTXO列表最大数量,如为0,表示无限制,LWS可以根据消息长度决定数量 2 TopicPrefix {$LWC-ID}的字符串表述,以 0 结尾 SignBytes Signature 字段字节数 2 Signature 用Address对应私钥对Payload除SignBytes/Signature以外数据块进行签名,签名方案为ED25519 SignBytes - Service Reply
主题(Topic): {$LWC-ID}/lwc/ServiceReply 调用方式: LWS → LWC 描述: LWS对Service Request的回复Payload：
Name Description Bytes Nonce 同对应 Service Request 中 Nonce 2 Version LWS 协议版本号 4 Error 0:无错误;1:不支持版本;2:无可用分支;3:地址不支持;4:拒绝服务;16:系统内部错误;17:系统满载。如有错误发生,后续没有AddressId/ForkBitmap/ApiKeySeed 1 AddressId LWS 分配的唯一非 0 标识 4 ForkBitmap 可提供服务的分支,根据 ServiceRequest提供的ForkList顺序,对Fork_i可提供服务bit_i为1,否则为0;bit顺序为LSB 8 ApiKeySeed 用于产生后续交互签名的ApiKey 32 -
Sync Request/Reply
- Sync Request
主题(Topic): {$LWS-ID}/lws/SyncReq 调用方式: LWC → LWS 描述: LWC同步UTXO列表请求Payload：
Name Description Bytes Nonce 非重复事务 ID ,由 LWC 分配非 0 唯一 ID 2 Address ServiceReply 中指定唯一标识 4 ForkID 请求同步的分支链ID 32 UTXOHash LWC本地对应ForkID的UTXOHash 32 Signature 用ApiKey对Payload除Signature以外数据块进行签名,签名方案为HMAC-RIPEMD-160 20 - Sync Reply
主题(Topic): {$LWC-ID}/lwc/SyncReply 调用方式: LWS → LWC 描述: LWS对Sync Request的回复Payload：
Name Description Bytes Nonce 同对应 Sync Request 中 Nonce 2 Error 0:无错误,已同步;1:UTXOHash不匹配;2:无效AddressId;3:无效分支;16:系统内部错误。如Error不等于0或1,后续没有BlockHash/BlockHeight/UTXONum/UTXOList/Continue 1 BlockHash 当前分支最后区块 hash 32 BlockHeight 当前分支最后区块高度 4 BlockTime 当前分支最后区块时间戳 4 UTXONum 当前消息中包含UTXO数量,如ServiceRequest中ReplyUTXON不为0,则UTXONum不能超过ReplyUTXON 2 UTXOList UTXO 列表 Continue 0: UTXO 列表结束, 1: UTXO 列表未完 1 -
SendTx Request/Reply
- SendTx Request
主题(Topic): {$LWS-ID}/lws/SendTxReq 调用方式: LWC → LWS 描述: LWC发送Tx请求Payload：
Name Description Bytes Nonce 非重复事务ID ,由LWC分配非0唯一ID 2 AddressId ServiceReply中指定唯一标识 4 ForkID 发送 Tx 所属的分支 ID 32 TxData 待发送 Tx 序列化数据 Signature 用ApiKey对Payload除Signature以外数据块进行签名, 签名方案为HMAC-RIPEMD-160 20 - SendTx Reply
主题(Topic): {$LWC-ID}/lwc/SendTxReply 调用方式: LWS → LWC 描述: LWS对SendTx Request的回复Payload：
Name Description Bytes Nonce 同对应SendTx Request中Nonce 2 Error 0:无错误;1:无效AddressId;2:无效分支;3:钱包节点返回错误;4:LWS校验错误; 16:系统内部错误。如Error不等于3或4,后续没有ErrCode/ErrDesc 1 ErrCode 钱包节点返回错误码 / LWS 校验错误码 1 ErrDesc 钱包节点返回错误 /LWS 校验错误描述,字符串表述,以 0 结尾