@electrum-cash/network 3.2.0-development.5350390388-r2-development.5350390388

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 GeneralProtocols
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# electrum-cash
+
+Electrum-cash is a lightweight `JavaScript` library that lets you connect with one or more `Electrum` servers.
+It offers encrypted connections by default,
+performs the expected protocol version negotiation and
+automatically keeps your connection alive until your close it.
+
+## Installation
+
+Install the library with NPM:
+
+```bash
+# npm install electrum-cash
+```
+
+## Usage
+
+### Load library
+
+Before you can use the library you need to include it in your project.
+
+If you only want to use a **single server**, load the `ElectrumClient` module:
+
+```js
+// Load the electrum library.
+const { ElectrumClient } = require('electrum-cash');
+```
+
+If you want to use **multiple servers**, load the `ElectrumCluster` module:
+
+```js
+// Load the electrum library.
+const { ElectrumCluster } = require('electrum-cash');
+```
+
+### Connect to servers
+
+After you have loaded the appropriate module you need to initialize the module by configuring your **application identifier** and **protocol version**.
+
+If you only want to use a single server, initialize an `ElectrumClient` and connect to the server:
+```js
+// Initialize an electrum client.
+const electrum = new ElectrumClient('Electrum client example', '1.4.1', 'bch.imaginary.cash');
+
+// Wait for the client to connect
+await electrum.connect();
+```
+
+If you want to use multiple servers, initialize an `ElectrumCluster` and add some servers:
+
+*For more information on various cluster configurations, read the [cluster documentation](https://read.cash/@JonathanSilverblood/electrum-cash-strategic-use-of-clusters-83743111).*
+
+```js
+// Initialize an electrum cluster where 2 out of 3 needs to be consistent, polled randomly with fail-over (default).
+const electrum = new ElectrumCluster('Electrum cluster example', '1.4.1', 2, 3);
+
+// Add some servers to the cluster.
+electrum.addServer('bch.imaginary.cash');
+electrum.addServer('electroncash.de');
+electrum.addServer('electroncash.dk');
+electrum.addServer('electron.jochen-hoenicke.de', 51002);
+electrum.addServer('electrum.imaginary.cash');
+
+// Wait for enough connections to be available.
+await electrum.ready();
+```
+
+### Request information
+
+Once your `ElectrumClient` or `ElectrumCluster` is connected and ready, you can call methods:
+
+*For a list of methods you can use, refer to the [Electrum Cash documentation](https://bitcoincash.network/electrum/).*
+
+```js
+// Declare an example transaction ID.
+const transactionID = '4db095f34d632a4daf942142c291f1f2abb5ba2e1ccac919d85bdc2f671fb251';
+
+// Request the full transaction hex for the transaction ID.
+const transactionHex = await electrum.request('blockchain.transaction.get', transactionID);
+
+// Print out the transaction hex.
+console.log(transactionHex);
+```
+
+### Subscribe to notifications.
+
+Once your `ElectrumClient` or `ElectrumCluster` is connected and ready, you can set up subscriptions to get notifications on events:
+
+*For a list of methods you can subscribe to, refer to the [Electrum Cash documentation](https://bitcoincash.network/electrum/).*
+
+```js
+// Set up a callback function to handle new blocks.
+const handleNotifications = function(data)
+{
+	if(data.method === 'blockchain.headers.subscribe')
+	{
+		// Print out the block information.
+		// {
+		// 	jsonrpc: '2.0',
+		// 	method: 'blockchain.headers.subscribe',
+		// 	params:
+		// 	[
+		// 		{
+		// 		height: 797111,
+		// 		hex: '002001202a6b1367f68201ad957e95bec9bda3f132ca2fcb75c0c000000000000000000074befba60bd8615d87ddb636aa99bc032cec8db3adb0d915d45391bc811c1e9ceacf89647a60051819a79559'
+		// 		}
+		// 	]
+		// }
+		console.log(data);
+	}
+}
+
+// Listen for notifications.
+electrum.on('notification', handleNotifications);
+
+// Set up a subscription for new block headers.
+await electrum.subscribe('blockchain.headers.subscribe');
+```
+
+### Shutting down
+
+When you're done and don't want to be connected anymore you can disconnect the server(s).
+
+If you're using a single `ElectrumClient`, call the `disconnect()` function:
+
+```js
+// Close the connection.
+await electrum.disconnect();
+```
+
+If you're using a `ElectrumCluster` with multiple servers, call the `shutdown()` function.
+
+```js
+// Close all connections.
+await electrum.shutdown();
+```
+
+## Documentation
+
+For a complete list of methods and parameters, read the [API documentation](https://generalprotocols.gitlab.io/electrum-cash/library/).
+
+## Support and communication
+
+If you need help with how to use the library or just want to talk about electrum-cash, you can find us on [Telegram](https://t.me/electrumcash) and [Discord](https://discord.gg/ZjXQzew).
+
+You can also read our tutorials on [read.cash](https://read.cash/c/electrum-cash-f45e), or share your own.
+
+## Notes
+
+The keep-alive functionality of this library only works when the protocol version is 1.2 or higher.