LWS Interface Description
LWS (Light wallet service) is an extendable light wallet service platform. As the inter-service of the BigBang core network and IOT devices, it provides a network connection for IOT devices that runs LWC and thereafter achieves synchronization of the devices’ transaction data and transaction delivery.
The IOT device network, in terms of its application, is characterized by low bandwidth, high concurrence, etc. It is quite demanding with regard to response delay and power consumption. Traditional internet technology prioritizes improvement in stability, safety and human-machine interaction experience, but in the case of IOT application excessive bandwidth is occupied. Additionally, it cannot support the multitude of devices connected and simultaneously achieve high concurrence and low network delay.
For IOT applications, at the moment a variety of IOT network protocols, including MQTT, COAP, AMQP and DDS, are supported by many IOT enterprises. Network service providers such as Amazon, IBM, Alibaba Cloud, Tencent Cloud are starting their data access service on IOT devices, offering MQTT and COAP protocols for IOT devices’ access, verification and resource management, as well as TLS security protocol to guarantee link data security. MQTT is the underlying transport protocol for the communication between LWS and IOT devices. This document is a description of MQTT’s transport requirements and application-layer protocol specifications.
Conform to MQTT v3.1.1 protocol specifications as follows:
1.QoS is set to QoS0 in Service Request; other commands are set to QoS1 with the maximum times of retransmission as 3.
-
Length of message is within 500B.
-
LWS, LWC agree MQTT’s topic format as follows:
{$LWS-ID}/lwc/{$FUNCTION}
{$LWC-ID}/lwc/{$FUNCTION}
4.The numerical variable in Payload is stored as little endian.
- Service Request
Topic: {$LWS-ID}/lws/ServiceReq
Way of calling: LWC→LWS
Description: Service Request after LWC is online
Payload：
| Name | Description | Bytes |
|---|---|---|
| Nonce | Non-repeated matter ID, unique non-zero ID is assigned by LWC | 2 |
| Address | LWC address | 33 |
| Version | LWC protocol version number | 4 |
| TimeStamp | Unix timestamp | 4 |
| ForkNum | Number of request branch lists, no more than 64 | 1 |
| ForkList | Request branch ID lists | 32*ForkNum |
| ReplyUTXO | The maximum number of lists, 0 means the number is limitless, LWS can decide the number according to length of message | 2 |
| TopicPrefix | {$LWC-ID}’s string representation, ends with 0 | |
| SignBytes | Number of bytes in Signature field | 2 |
| Signature | To sign on data blocks other than SignBytes/Signature using Address’ corresponding private keys, signature scheme is ED25519 | SignBytes |
- Service Reply
Topic: {$LWC-ID}/lwc/ServiceReply
Way of calling: LWS→LWC
Description: LWS’s reply to Service Request
Payload：
| Name | Description | Bytes |
|---|---|---|
| Nonce | Same as the Nonce in corresponding Service Request | 2 |
| Version | LWS protocol version number | 4 |
| Error | 0: no error;1: version not supported; 2: no branch available; 3: address not supported; 4: denial of service; 16: system internal error; 17: system fully loaded. If an error occurs, no following AddressId/ForkBitmap/ApiKeySeed | 1 |
| AddressId | LUnique non-zero identification assigned by LWS | 4 |
| ForkBitmap | Forklist order, for available service of Fork I, bit_i is 1, 0 otherwise; order is LSB | 8 |
| ApiKeySeed | ApiKey used to produce following interactive signature | 32 |
Topic: {$LWS-ID}/lws/SyncReq
Way of calling: LWC→LWS
Description: LWC’s request to synchronize UTXO list
Payload：
| Name | Description | Bytes |
|---|---|---|
| Nonce | Non-repeated matter ID, unique non-zero ID is assigned by LWC | 2 |
| Address | Designated only identification in ServiceReply | 4 |
| ForkID | The branch link ID that requests synchronization | 32 |
| UTXOHash | LWC’s UTXOHash that corresponds with ForkID locally | 32 |
| Signature | Using ApiKey to sign on data blocks of Payload other than Signature, signature scheme is HMAC-RIPEMD-160 | 20 |
Sync Reply
Topic: {$LWC-ID}/lwc/SyncReply
Way of calling: LWS→LWC
Description: LWS’s reply to Sync Request
Payload：
| Name | Description | Bytes |
|---|---|---|
| Nonce | Same as the Nonce in corresponding Sync Request | 2 |
| Error | 0: no error, synchronization finished; 1: UTXOHash not matched; 2: invalid AddressId; 3: invalid branch; 16: system internal error. If error is not 0 or 1, then no following BlockHash/BlockHeight/UTXONum/UTXOList/Continue | 1 |
| BlockHash | The last block hash of current branch | 32 |
| BlockHeight | The last block height of current branch | 4 |
| BlockTime | The last block timestamp of current branch | 4 |
| UTXONum | Number of UTXO contained in current message, for example, if ReplyUTXON in ServiceRequest is not 0, UTXONum cannot exceed ReplyUTXON | 2 |
| UTXOList | UTXO list | |
| Continue | 0: UTXO list ends, 1: UTXO list not ended | 1 |
- SendTx Request
Topic: {$LWS-ID}/lws/SendTxReq
Way of calling: :LWC→LWS
Description: LWC sends Tx request
Payload：
| Name | Description | Bytes |
|---|---|---|
| Nonce | Non-repeated matter ID, unique non-zero ID is assigned by LWC | 2 |
| AddressId | Designated only identification in ServiceReply | 4 |
| ForkID | Branch ID that sends where Tx is | 32 |
| TxData | Serialized Tx data pending sending | |
| Signature | Using ApiKey to sign on data blocks of Payload other than Signature, signature scheme is HMAC-RIPEMD-160 | 20 |
- SendTx Reply
Topic: {$LWC-ID}/lwc/SendTxReply
Way of calling: LWS→LWC
Description: LWS’s reply to SendTx Request
Payload：
| Name | Description | Bytes |
|---|---|---|
| Nonce | Same as the Nonce in corresponding SendTx Request | 2 |
| Error | 0: no error; 1: invalid AddressId; 2: invalid branch; 3: wallet node return error; 4: LWS check error; 16: system internal error. If Error is not equal to 3 or 4, no following ErrCode/ErrDesc | 1 |
| ErrCode | Wallet node return error code/ LWS check error code | 1 |
| ErrDesc | Wallet node return error/ LWS check error description, represented in character string, ends with 0 |