Implementation of the Stratum protocol (for electrum and mining) using ReactPHP
The Client class is used to make a connection to a host. It takes a ConnectorInterface
and RequestFactory.
react/socket-client provides a number of connectors, which can be combined
to produce the desired functionality.
use \BitWasp\Stratum\Client;
use \BitWasp\Stratum\Connection;
use \BitWasp\Stratum\Request\RequestFactory;
$loop = \React\EventLoop\Factory::create();
$resolver = new \React\Dns\Resolver\Factory();
// Raw TCP, cannot perform DNS resolution
$tcp = new \React\SocketClient\TcpConnector($loop);
// TCP Connector with a DNS resolver
$dns = new \React\SocketClient\DnsConnector($tcp, $resolver->create('8.8.8.8', $loop));
// Encrypted connection
$context_options = [];
$tls = new \React\SocketClient\SecureConnector($dns, $loop, $context_options);
$requests = new RequestFactory;
$client = new Client($tls, $requests);
$host = '';
$port = '';
$client->connect($host, $port)->then(function (Connection $conn) {
/* success */
}, function (\Exception $e) {
/* error */
print_r($e->getMessage());
});
$loop->run();The SecureConnector initiates a TLS session to encrypt your connection. $context_options is an optional value, but many Electrum servers have misconfigured SSL certificates! (incorrect CN field, or are self-signed) These will not be accepted with the default verification settings, and can be disabled by changing the $context_options
$context_options = ["verify_name" => false, "allow_self_signed" => true];
A Connection represents a connection to a peer.
Requests can be sent to the peer using Connection::request($method, $params = []),
which returns a Promise for the pending result. When a response with the same ID is
received, the promise will resolve this as the result.
$conn->request('server.banner')->then(function (Response $response) {
print_r($response->getResult());
}, function (\Exception $e) {
echo $e->getMessage();
});Request instances can be sent using Connection::sendRequest(Request $request)
which also returns a promise.
For a list of methods for the electrum and mining clients, see the respective Api classes. The constants are method's for these APIs.
$conn->sendRequest(new Request(null, 'server.banner'))->then(function (Response $response) {
print_r($response->getResult());
}, function (\Exception $e) {
echo $e->getMessage();
});NotificationInterface's can be sent using Connection::sendNotify(NotificationInterface $note)
Notifications are not requests, and don't receive a response. This method is only relevant if
using Connection from a servers perspective.
$conn->sendNotification(new NumBlocksNotification(123123));The Stratum protocol is implemented by electrum servers and stratum mining pools.
Their methods are exposed by ElectrumClient and MiningClient respectively.
The api methods cause a Request to be sent, returning a promise to capture the result.
use \BitWasp\Stratum\Api\ElectrumClient;
use \BitWasp\Stratum\Client;
use \BitWasp\Stratum\Connection;
use \BitWasp\Stratum\Request\RequestFactory;
$loop = React\EventLoop\Factory::create();
$tcp = new \React\SocketClient\TcpConnector();
$requests = new RequestFactory;
$client = new Client($tls, $requests);
$client->connect($host, $port)->then(function (Connection $conn) {
$electrum = new ElectrumClient($conn);
$electrum->addressListUnspent('1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L')->then(function (Response $response) {
print_r($response->getResult());
});
}, function (\Exception $e) {
/* error */
});
$loop->run();Connection emits a message event when a message is received which
was not initiated by a Request. These messages are typically due to subscriptions.
The following events are emitted automatically by the library when encountered. The event name is the method used to enable the subscription.
- 'blockchain.headers.subscribe' emits a
HeadersNotification - 'blockchain.address.subscribe' emits a
AddressNotification - 'blockchain.numblocks.subscribe' emits a
NumBlocksNotification - 'mining.subscribe' emits a
MiningNotification - 'mining.set_difficulty' emits a
SetDifficultyNotification
use \BitWasp\Stratum\Api\ElectrumClient;
use \BitWasp\Stratum\Client;
use \BitWasp\Stratum\Connection;
use \BitWasp\Stratum\Request\RequestFactory;
$loop = React\EventLoop\Factory::create();
$tcp = new \React\SocketClient\TcpConnector();
$requests = new RequestFactory;
$client = new Client($tls, $requests);
$client->connect($host, $port)->then(function (Connection $conn) {
$conn->on('message', function ($message) {
echo "Message received: ".PHP_EOL;
print_r($message);
});
$conn->on(ElectrumClient::ADDRESS_SUBSCRIBE, function (AddressNotification $address) {
echo "Received address update\n";
});
$electrum = new ElectrumClient($conn);
$electrum->subscribeAddress('1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L');
}, function (\Exception $e) {
/* error */
});
$loop->run();