Subscriptions are disabled.

[narodnik]

https://github.com/libbitcoin/libbitcoin-server/blob/master/src/interface/address.cpp

Just keeping a note about it here for version 3.

[evoskuil]

Yes, currently disabled in version3, but renew and update are not coming back. A resubscription will take their place. It will trasparentky renew if same subscription or create a subscription if not.

[narodnik]

OK, probably there should be a single method for the prefix which matches against both stealth and normal addresses, and ignores the version. The data returned should only be [ height ][ block_hash ][ tx_data ]. The height is used for counting confirmations, and the block_hash is useful for tracking reorgs. The client should be checking the tx_data, and discarding non-matching txs (which would rarely happen with a big enough prefix).

[evoskuil]

See address notification schema. Also see address.subscribe schema.

These are consistent with v2 except for renewals.

[narodnik]

These can be improved.

Subscribe: [ bitsize:1 ][ blocks ]

Update: [ height:4 ][ block_hash: 32 ][ tx_data ]

[evoskuil]

Agree, but it's a compatibility break. We can change the version and drop the previous.

[narodnik]

Well this API (subscribe) has already been broken with the format change, so you might as well make these changes as well. Putting the type (stealth or address) in the request, and including either the address or the stealth data in the response was a mistake in hindsight.

The design philosophy of the API (in general) is minimal, pure and fast. Therefore the API does not (generally) include more data than is needed, that the client can deduce with extra computation.

In this case, the client should be deserializing the tx_data, and checking the inputs and outputs themselves, to understand why the server sent it to them. The client should be checking it against the prefixes it knows that it's subscribed to.

There are 2 other things worth considering:

While implementing the protocol (client side) yesterday, I made a generic deserializer for all message types that splits the 4 byte error code from the rest of the data. It worked great, until I had to deal with address.update which has no error code.

I think that all messages sent from a bs should include a 4 byte error_code without exception. This is also a field that we may want to use in the future:

• Imagine we subscribe, the server has reached its subscribe limit, and sends an update saying the client cannot be subscribed (error_code::subscribe_limit_reached).
• Maybe we decide to notify hosts that we are desubscribing them.

https://github.com/RojavaCrypto/python-libbitcoin/blob/master/libbitcoin/poller.py#L48

That's the line in question which is broken for address.update and cannot be generically used.

The other thing- would it possibly be worth having a desubscribe too? ZMQ doesn't give disconnect notifcations, but would it help if clients were unsubscribing from the server before disconnecting? It would help save resources for the wallets correctly implemented rather than everyone just letting the server expire their subscription after 10 minutes that we use now. But maybe there's also value in having a simpler API, and we can always add this later rather than sooner (time to think about it) since it only extends the API.

Generally the fetch/query API is well thought out, but this address.subscribe stuff was made in a hurry and is relatively newer. What I wrote above should work well though (request=prefix, response=block_id+tx). The block_height and block_hash tuple is so far the only method I know for correctly identifying a block that I'm sure is fool proof, and is used elsewhere in the server API.

[evoskuil]

Yes, all makes sense. I was considering the unsubscribe as well.

[evoskuil]

It is unfortunate the the existing protocol incorporates the result code into the payload as opposed to a standard zeromq message frame, but for the sake of backward compat this will also be the case for notifications.

[evoskuil]

Subscriptions are enabled as of #233.

This includes new implementation of support for the old (v2) protocol address.subscribe and address.renew with address.update responses. These three messages are supported in v3 but deprecated and are slated for obsolescence in v4. Both stealth prefix and address prefix subscription types remain supported. There should be wire equivalence with v2. The payload format of the v2 messages follows:

address.subscribe

    // request
    // [ type:1 ] (0 = address prefix, 1 = stealth prefix)
    // [ prefix_bitsize:1 ]
    // [ prefix_blocks:...]

    // response
    // [ code: 4 ]

address.renew

    // request
    // [ type:1 ] (0 = address prefix, 1 = stealth prefix)
    // [ prefix_bitsize:1 ]
    // [ prefix_blocks:...]

    // response
    // [ code: 4 ]

address.update (address prefix)

    // [ address.version:1 ]
    // [ address.hash:20 ]
    // [ height:4 ]
    // [ block_hash:32 ]
    // [ tx:... ]

address.update (stealth prefix)

    // [ prefix:4 ]
    // [ height:4 ]
    // [ block_hash:32 ]
    // [ tx:... ]

This also includes new address.subscribe2 and address.unsubscribe2 messages. v2 did not implement an unsubscribe and v3 does not implement a renew message. Unsubscription uses the same parameterization as subscription and responds in the same manner. Renewal in v2 is implemented by simply sending the subscription again.

There is no indication in the subscription response that a previous subscription did or did not previously exist. However, all subscription terminations, including unsubscription and expiration, result in a notification with the appropriate error code (error::channel_stopped or error::channel_timeout respectively). All messages in the v3 API have a payload predicated with an error code (in which case subsequent bytes are not guaranteed). Currently address.subscribe2 and address.unsubscribe2 responses always succeeded as long as the request is properly formatted. In the case of a full subscription queue a subsequent update is sent with an error code (terminating the subscription).

Updates in v3 include a zero-based sequence number. As messages may be dropped under heavy load this allows the caller to detect a missed update. The payload format of the v3 messages follows:

address.subscribe2

    // request
    // [ prefix_bitsize:1 ]
    // [ prefix_blocks:...]

    // response
    // [ code: 4 ]

address.unsubscribe2

    // request
    // [ prefix_bitsize:1 ]
    // [ prefix_blocks:...]

    // response
    // [ code: 4 ]

address.update2

    // [ code:4 ]
    // If code is non-zero then this section is not included and the subscription is terminated.
    // [ sequence:1 ]
    // [ height:4 ]
    // [ block_hash:32 ]
    // [ tx:... ]

Receipt of notification messages is not yet testable because the node is not enabled past initial block download (coming soon).