Skip to main content

Subscription API

This proposal aims to aid the contract tracing proposal, by providing an external API to query the data. And making real time data easier to access.

Motivation​

Current wallet implementations rely on polling the shell in order the know. When their balance has changed and when a transaction has gone through. The obviously superior alternative is to let the server notify the client when it has data. Be that via long-polling, socket, SSE etc... Note: the kernel node exposes a nng subscription socket which publishes all data to the connected clients where data is filtered client-side. This socket is not intended to be exposed externally.

Requirements​

The API should be content driven, cheap for the server decide which events to send, while stile being flexible enough the clients should do minimal filtering.

Proposed Solution​

The client sends a HiRPC with the subscribe method. The single parameter is object with the following structure.

struct SubFilter {
    @optional string typename;
    @optional DARTIndex[] dartindex;
    @optional Archive.Type
    bool verify() {
        return !typename.empty || !dartindex.empty;
    }
}

A response event should be the same format as the response to a dartRead command. It should contain a recorder with documents matching the filter.

Examples​

Subscribe to any new updated document which you own.

trt.subscribe

SubFilter sub;
sub.typename = "$@trt";
sub.dartindex = [dartindex(#$Y, <mypubkey>)];

Subscribe to new epochs

subscribe

SubFilter sub;
sub.typename = $@E;