Add missing files

2025-04-02 20:09:03 +00:00 · 2023-07-04 12:00:43 -04:00 · 2023-07-04 12:00:43 -04:00 · 7b932b7373
commit 7b932b7373
parent d78a920ba1
2 changed files with 131 additions and 0 deletions
--- a/docs/zmq.md
+++ b/docs/zmq.md
@ -0,0 +1,91 @@
+# monero-lws ZeroMQ Usage
+Monero-lws uses ZeroMQ-RPC to retrieve information from a Monero daemon,
+ZeroMQ-SUB to get immediate notifications of blocks and transactions from a
+Monero daemon, and ZeroMQ-PUB to notify external applications of payment_id
+(web)hooks.
+
+## External "pub" socket
+The bind location of the ZMQ-PUB socket is specified with the `--zmq-pub`
+option. Users are still required to "subscribe" to topics:
+  * `json-full-hooks`: A JSON array of webhook events that have recently
+    triggered (identical output as webhook).
+  * `msgpack-full-hooks`: A msgpack array of webhook events that have recently
+    triggered (identical output as webhook).
+
+
+### `json-full-hooks`/`msgpack-full-hooks`i
+These topics receive PUB messages when a webhook ([`webhook_add`](administration.md)),
+event is triggered. If the specified URL is `zmq`, then notifications are only
+done over the ZMQ-PUB socket, otherwise the notification is sent over ZMQ-PUB
+socket AND the specified URL. Invoking `webhook_add` with a `payment_id` of
+zeroes (the field is optional in `webhook_add), will match on all transactions
+that lack a payment_id`.
+
+Example of the "raw" output from ZMQ-SUB side:
+
+```json
+json-full-hooks:{
+  "index": 2,
+  "events": [
+    {
+      "event": "tx-confirmation",
+      "payment_id": "4f695d197f2a3c54",
+      "token": "single zmq wallet",
+      "confirmations": 1,
+      "event_id": "3894f98f5dd54af5857e4f8a961a4e57",
+      "tx_info": {
+        "id": {
+          "high": 0,
+          "low": 5666767
+        },
+        "block": 2265961,
+        "index": 0,
+        "amount": 100000000000,
+        "timestamp": 1687301600,
+        "tx_hash": "ef3187775584351cc5109de124b877bcc530fb3fdbf77895329dd447902cc566",
+        "tx_prefix_hash": "064884b8a8f903edcfebab830707ed44b633438b47c95a83320f4438b1b28626",
+        "tx_public": "54dce1a6eebafa2fdedcea5e373ef9de1c3d2737ae9f809e80958d1ba4590d74",
+        "rct_mask": "68459964f89d69b7a4b1e0a1a8a384cbc9a76363c8a6e99058d41906908bd005",
+        "payment_id": "4f695d197f2a3c54",
+        "unlock_time": 0,
+        "mixin_count": 15,
+        "coinbase": false
+      }
+    },
+    {
+      "event": "tx-confirmation",
+      "payment_id": "4f695d197f2a3c54",
+      "token": "single zmq wallet",
+      "confirmations": 1,
+      "event_id": "3894f98f5dd54af5857e4f8a961a4e57",
+      "tx_info": {
+        "id": {
+          "high": 0,
+          "low": 5666768
+        },
+        "block": 2265961,
+        "index": 1,
+        "amount": 3117324236131,
+        "timestamp": 1687301600,
+        "tx_hash": "ef3187775584351cc5109de124b877bcc530fb3fdbf77895329dd447902cc566",
+        "tx_prefix_hash": "064884b8a8f903edcfebab830707ed44b633438b47c95a83320f4438b1b28626",
+        "tx_public": "54dce1a6eebafa2fdedcea5e373ef9de1c3d2737ae9f809e80958d1ba4590d74",
+        "rct_mask": "4cdc4c4e340aacb4741ba20f9b0b859242ecdad2fcc251f71d81123a47db3400",
+        "payment_id": "4f695d197f2a3c54",
+        "unlock_time": 0,
+        "mixin_count": 15,
+        "coinbase": false
+      }
+    }
+  ]
+}
+```
+
+Notice the `json-full-hooks:` prefix - this is required for the ZMQ PUB/SUB
+subscription model. The subscriber requests data from a certain "topic" where
+matching is done by string prefixes.
+
+> `index` is a counter used to detect dropped messages.
+
+> The `block` and `id` fields in the above example are NOT present when
+`confirmations == 0`.
--- a/src/wire/adapted/span.h
+++ b/src/wire/adapted/span.h
@ -0,0 +1,40 @@
+// Copyright (c) 2023, The Monero Project
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without modification, are
+// permitted provided that the following conditions are met:
+//
+// 1. Redistributions of source code must retain the above copyright notice, this list of
+//    conditions and the following disclaimer.
+//
+// 2. Redistributions in binary form must reproduce the above copyright notice, this list
+//    of conditions and the following disclaimer in the documentation and/or other
+//    materials provided with the distribution.
+//
+// 3. Neither the name of the copyright holder nor the names of its contributors may be
+//    used to endorse or promote products derived from this software without specific
+//    prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
+// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+// THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+// THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#pragma once
+
+#include "span.h" // monero/contrib/epee/include
+#include "wire/traits.h"
+
+namespace wire
+{
+  //! Enable span types for array output
+  template<typename T>
+  struct is_array<epee::span<T>>
+    : std::true_type
+  {};
+}