From 95ec5308181a2e153daba36e23665256af129828 Mon Sep 17 00:00:00 2001 From: Just Wonder Date: Fri, 31 Jan 2020 18:47:22 -0800 Subject: [PATCH] Added Kevacoin ZeroMQ event notification. --- README.md | 5 ++-- doc/zmq.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 86 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e52c50e26..ec87c1d20 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ What does it do? What can it be used for? ------------------------ -As a decentralized key-value database, it can be used to store data for all kinds of applications, such as social media, microblogging, public identity information, notary service. Kevacoin has limited support for smart contracts (similar to Bitcoin and Litecoin), but one can still develop decentralized apps (dApps) on Kevacoin. The data is decentralized while the application logic is developed off the blockchain. +As a decentralized key-value database, it can be used to store data for all kinds of applications, such as social media, microblogging, public identity information, notary service. Kevacoin has limited support for smart contracts (similar to Bitcoin and Litecoin), but one can still develop decentralized apps (dApps) on Kevacoin. The data is decentralized while the application logic is developed off the blockchain. Our major observation for decentralized apps is that data is significantly more important than the application. In fact, that is the case for all kinds of applications. It is common these days to hear that companies rewrite their applications using better technologies, but it is rare for any of them to make big changes to their valuable data. @@ -26,7 +26,8 @@ the Kevacoin Core software, see [https://kevacoin.org](https://kevacoin.org). Documentation -------------- -[Command line and RPC documentation](https://kevacoin.org/documentation.html) +* [Command line and RPC documentation](https://kevacoin.org/documentation.html) +* [Kevacoin ZeroMQ Event Notification](doc/zmq.md) Build diff --git a/doc/zmq.md b/doc/zmq.md index e0acc3c7c..7969ba0b3 100644 --- a/doc/zmq.md +++ b/doc/zmq.md @@ -76,7 +76,15 @@ notification `-zmqpubhashtx` the topic is `hashtx` (no null terminator) and the body is the transaction hash (32 bytes). -These options can also be provided in kevacoin.conf. +These options can also be provided in kevacoin.conf. The following is an sample +kevacoin.conf file that support notification to Keva events: + +``` +rpcport=9332 +rpcuser=user +rpcpassword=userpassword +zmqpubkeva=tcp://127.0.0.1:29000 +``` ZeroMQ endpoint specifiers for TCP (and others) are documented in the [ZeroMQ API](http://api.zeromq.org/4-0:_start). @@ -86,6 +94,80 @@ ZMQ_SUBSCRIBE option set to one or either of these prefixes (for instance, just `hash`); without doing so will result in no messages arriving. Please see `contrib/zmq/zmq_sub.py` for a working example. +## Kevacoin Specific Events + +Once ZMQ notification is enabled for Keva events, it is easy to subscribe +to the events. The following is a NodeJS example: + +```js +var zmq = require('zeromq'); + +async function run() { + // Create a subscriber socket. + var sock = new zmq.Subscriber; + var addr = 'tcp://127.0.0.1:29000'; + + // Initiate connection to TCP socket. + sock.connect(addr); + + // Subscribe to receive messages for a specific topic. + // This can be "rawblock", "hashblock", "rawtx", or "hashtx". + sock.subscribe('keva'); + + for await (const [topic, message] of sock) { + if (topic.toString() === 'keva') { + let json = JSON.parse(message); + console.log('received keva:'); + console.log(json); + } + } +} + +run(); +``` + +Keva messages are in JSON format. This is an example of the `keva_update` messsage: + +```json +{ + tx: '690652bbee2bce22fdc9c5619ac77f3b7645423e2790860afa0fa2d14ff0c1be', + height: 10673, + timestamp: 1580520584, + type: 'keva_update', + namespace: 'Nd25va1gcEFjWgJtzU7Vuu3dG7gWE7G77y', + key: 'This is key', + value: 'This is value' +} +``` + +This is an example of the `keva_namespace` (creation of namespace) messsage: + +```json +{ + tx: 'a6b4792a2150e1f15a45ff658dbfc64f34a0b0b27270321f557acfa0f70027d6', + height: 10677, + timestamp: 1580520947, + type: 'keva_namespace', + namespace: 'NRT9nLFy433BWeBakmyV1TFugai6dZt7BH' +} +``` + +When developing applications on Kevacoin, it is convenient to be able to subscribe to certain Keva events. For example, a Twitter-like application on Keva blockchain can listen to the event that a user follows the other user. Assume that the follower adds a key to her own namespace (`N_follower`) to indicate that she is following the other user whose namespace is `N_celeb`: + +``` +keva_put true +``` + +The application listening to this kind of event will be notified, and then when `N_celeb` publishes a new update, the application will notify the follower. + +Similarly, if the follower stops following, she can set the value to `false`: +``` +keva_put true +``` +The application will also receive this event and stop send her the updates. + +Note that the data is completely on the blockchain and the application can be written by anyone. The developer of the application has no monopoly on the data. The pub/sub APIs make it easier to develop applications, though technically the data on the blockchain provides sufficient information and is the single source of truth. + ## Remarks From the perspective of kevacoind, the ZeroMQ socket is write-only; PUB