@scintilla-network/quorums

Overview

@scintilla-network/quorums is a library designed to facilitate the creation, management, and communication of decentralized quorums within the Scintilla Network.

This library includes classes and utilities for such.

• By having each peers registered with their identity, each peer can be identified
• Any known connections is added to the peer list and its state changes accross time. It shall be taken into account that peers ip addresses can be reused by other peers (like with AWS).
• Therefore, peers are identified with {moniker}::{ip}:{port} system (that's the network identifier for peer).

Peers

Peers in the system are identified by their moniker, ip address and port (e.g. alice::52.23.30.1:8900).
The moniker allows for secure exchange of messages between peers as the identity contains the public key of the peer. The ip address and port are used to establish a connection between peers and to locate them in the network.

Additionally, peers can be more specifically identified by theit quorum cluster they belong to (e.g. alice::52.23.30.1:8900@scintilla).

Installation

To install @scintilla-network/quorums, use npm:

npm install @scintilla-network/quorums

Usage

Here's an example of how to create a quorum network, add identities, and start the network:

QuorumNetwork Example

import QuorumNetwork from '@scintilla-network/quorums/QuorumNetwork';
import { Identity } from '@scintilla-network/sdk';

const id = {
    parent: null,
    moniker: 'scintilla',
    members: [['core', 1000, 1000, 0, 0, 0, 0]],
    records: {
        modules: {
            'core.identity': {
                actions: {
                    PROPOSAL_CREATE: [{
                        condition: {
                            all: [{ fact: 'identity#parent', operator: 'IN', value: ['sct', 'core', 'scintilla'] }]
                        },
                        type: 'ALLOW'
                    }]
                }
            },
            scintilla: {
                consensus: {
                    members: [['sct.yggdrasil.coordinator', 1000]],
                    type: 'COORDINATOR_PROOF'
                }
            }
        }
    },
    childs: []
};

const qnet = new QuorumNetwork({
    quorum: 'scintilla',
    moniker: 'alice'
});

(async () => {
    // Initialize and start the network, load prior state
    await qnet.init();
    
    // Update identities
    qnet.updateIdentity(new Identity(id));

    // Open the network on port 8900
    // Allow to relay messages to other peers
    await qnet.open(8900);
    
    // Connect to peers, by default, the network will connect to one or all quorum members 
    await qnet.connect();
    
    // Start the network
    await qnet.start();

    console.log({ qnet });
    console.log(qnet.connections);
})();

Components

• IdentitiesMap: Manages a collection of identity objects. Read more
• NetRequest: Represents a network request with capabilities for encryption, signing, and verification. Read more
• NetResponse: Represents a response to a network request. Read more
• PeerMap: Manages a collection of peers. Read more
• QuorumIdentity: Represents an identity within a quorum. Read more
• QuorumMember: Represents a member within a quorum. Read more
• QuorumNetwork: Manages the overall quorum network, including peer connections and communication. Read more
• QuorumPeer: Represents a peer in the quorum network. Read more
• TCPConnection: Represents a TCP connection. Read more
• TCPServer: Represents a TCP server. Read more
• Queue: Represents a queue data structure. Read more
• Stack: Represents a stack data structure with message processing capabilities. Read more
• QuorumDecision: Represents a decision made by the quorum, with support for signing and verifying multiple authorizations. Read more
• QuorumDecisionVote: Represents a vote on a QuorumDecision. Read more

IdentitiesMap

Manages a collection of identity objects.

Example:

import IdentitiesMap from '@scintilla-network/quorums/IdentitiesMap';

const identities = new IdentitiesMap();
identities.set(someIdentity);
const retrievedIdentity = identities.get(someMoniker);

NetRequest

Represents a network request with capabilities for encryption, signing, and verification.

Example:

import NetRequest from '@scintilla-network/quorums/NetRequest';

const netRequest = new NetRequest({
    source: 'source',
    destination: 'destination',
    method: 'GET',
    path: '/blocks/current',
    payload: [],
});

console.log(netRequest.toHex());

NetResponse

Represents a response to a network request.

Example:

import NetResponse from '@scintilla-network/quorums/NetResponse';

const netResponse = new NetResponse({
    request: 'someRequestId',
    destination: 'destination',
    source: 'source',
    code: 200,
    payload: [],
});

console.log(netResponse.toHex());

PeerMap

Manages a collection of peers.

Example:

import PeerMap from '@scintilla-network/quorums/PeerMap';

const peers = new PeerMap();
peers.set('identifier', somePeer);

QuorumIdentity

Represents an identity within a quorum.

Example:

import QuorumIdentity from '@scintilla-network/quorums/QuorumIdentity';

const quorumIdentity = new QuorumIdentity(someIdentity);
console.log(quorumIdentity.getMembers());

QuorumMember

Represents a member within a quorum.

Example:

import QuorumMember from '@scintilla-network/quorums/QuorumMember';

const quorumMember = new QuorumMember(someIdentity, someQuorumIdentity);
console.log(quorumMember.getNetworkInfo());

QuorumNetwork

Manages the overall quorum network, including peer connections and communication.

Example:

import QuorumNetwork from '@scintilla-network/quorums/QuorumNetwork';

const qnet = new QuorumNetwork({
    quorum: 'scintilla',
    moniker: 'alice'
});

await qnet.init();
await qnet.open(8900);
await qnet.connect();
await qnet.start();

QuorumPeer

Represents a peer in the quorum network.

Example:

import QuorumPeer from '@scintilla-network/quorums/QuorumPeer';

const qp = new QuorumPeer(someQuorumMember);
await qp.connect();

TCPConnection

Represents a TCP connection.

Example:

import TCPConnection from '@scintilla-network/quorums/TCPConnection';

const conn = new TCPConnection();
await conn.connect({ port: 8888, host: 'localhost' });
conn.send(someData);

TCPServer

Represents a TCP server.

Example:

import TCPServer from '@scintilla-network/quorums/TCPServer';

const server = new TCPServer();
await server.listen(8888);
server.broadcast(someData);

Queue

Represents a queue data structure.

Example:

import Queue from '@scintilla-network/quorums/Queue';

const queue = new Queue();
queue.enqueue(someItem);
console.log(queue.dequeue());

Stack

Represents a stack data structure with message processing capabilities.

Example:

import Stack from '@scintilla-network/quorums/Stack';

const stack = new Stack();
stack.push(someData);
console.log(stack.processMessages());

QuorumDecision

Represents a decision made by the quorum, with support for signing and verifying multiple authorizations.

Example:

import QuorumDecision from '@scintilla-network/quorums/QuorumDecision';

const decision = new QuorumDecision({
    proposer: 'proposer1',
    cluster: 'cluster1',
    quorum: 'quorum1',
    payload: { data: 'test' },
    action: 'ADD_MEMBER',
});
await decision.sign(signer);
console.log(decision.verify());

QuorumDecisionVote

Represents a vote on a QuorumDecision.

Example:

import QuorumDecisionVote from '@scintilla-network/quorums/QuorumDecisionVote';

const vote = new QuorumDecisionVote({
    decision: 'decision1',
    voter: 'voter1',
    vote: 'YES',
});

console.log(vote.getVote());

Detailed Documentation

For more details on each component, refer to the individual documentation files:

• IdentitiesMap
• NetRequest
• NetResponse
• PeerMap
• QuorumIdentity
• QuorumMember
• QuorumNetwork
• QuorumPeer
• TCPConnection
• TCPServer
• Queue
• Stack
• QuorumDecision
• QuorumDecisionVote