Connect and interact with nodes in the Stellar Network over the tcp protocol.
This package consists of two main classes. Node and Connection.
The Node class allows you to connect to and accept connections from other nodes.
A connection to a Node is encapsulated in the Connection class. It handles the Stellar Network handshake and message authentication. It is a custom duplex stream in object mode that wraps a tcp socket and respects backpressure. It emits and allows you to send Stellar Messages .
Stellar Messages are the xdr structures used in Stellar core used to pass data between nodes. They are made available in javascript thanks to the Stellar base and js-xdr packages.
pnpm install
pnpm run build : builds code in lib folder
pnpm run test
import { createNode } from 'src'
let node = createNode(true, getConfigFromEnv());
//Interact with the public network. Configuration in environment variables. Uses defaults if env values are missing.`
let connection:Connection = node.connectTo(peerIp, peerPort); //connect to a node;
The Connection class wraps a net socket and emits the same events with two twists:
- the connect event includes PublicKey and NodeInfo (version, overlayVersion,...).
- data/readable passes StellarMessageWork objects that contain StellarMessages and a 'done' callback. The done callback is needed for the custom flow control protocol implemented in stellar nodes. This protocol controls the amount of flood messages (transaction, scp) that are sent to peers.
For example handling an SCP message:
connection.on("data", (stellarMessageWork: StellarMessageWork) => {
const stellarMessage = stellarMessageWork.stellarMessage;
if (stellarMessage.switch().value === MessageType.scpMessage().value) {
console.log(stellarMessage.envelope().signature().toString());
//do work...
//signal done processing for flow control
stellarMessageWork.done();
}
}
To send a StellarMessage to a node use the sendStellarMessage or more generic write method:
connection.sendStellarMessage(StellarMessage.getScpState(0));
Disclaimer: at the moment this is rather limited and only used for integration testing. For example flow control is not implemented
node.acceptIncomingConnections(11623, '127.0.0.1');
node.on("connection", (connection:Connection) => {
connection.on("connect", () => {
console.log("Fully connected and ready to send/receive Stellar Messages");
});
connection.on("data", (stellarMessageWork: StellarMessageWork) => {
//do something
});
});
Checkout the NodeConf class. The following env parameters are available:
- LOG_LEVEL=debug | info | trace
- PRIVATE_KEY //If no secret key is supplied, one is generated at startup.
- LEDGER_VERSION
- OVERLAY_VERSION
- OVERLAY_MIN_VERSION
- VERSION_STRING
- LISTENING_PORT=11625
- RECEIVE_TRANSACTION_MSG=true //will the Connection class emit Transaction messages
- RECEIVE_SCP_MSG=true //will the Connection class emit SCP messages
- PEER_FLOOD_READING_CAPACITY=200 //max number of messages that can be processed simultaneously from a peer
- FLOW_CONTROL_SEND_MORE_BATCH_SIZE=40 //number of messages that can be received before sending a FLOW_CONTROL_SEND_MORE and reclaiming flood reading capacity
- PEER_FLOOD_READING_CAPACITY_BYTES=3000000 //max number of bytes that can be processed simultaneously from a peer
- FLOW_CONTROL_SEND_MORE_BATCH_SIZE_BYTES=1000000 //number of bytes that can be received before sending a FLOW_CONTROL_SEND_MORE and reclaiming flood reading capacity //see stellar core config for info on flood control parameters
You can connect to any node with the example script:
pnpm examples:connect ip port
You can find ip/port of nodes on https://stellarbeat.io
The script connects to the node and logs the xdr stellar messages it receives to standard output. Using Stellar laboratory you can inspect the content of the messages without coding.
pnpm np