Open-source toolkit
for peer-to-peer protocols

Install 1.2.0

From the package registries. Python 3.9+, a Rust toolchain, and Node 20+.

pip install chaincraft
cargo install chaincraft
npm install --global @chaincraft/core

cargo add chaincraft and npm install @chaincraft/core are the library installs, for the programs below. Clone only if you want the source tree: git clone https://github.com/jose-compu/chaincraft-monorepo.git.

Browser

@chaincraft/core/browser does not import the TCP mesh. It asks https://dechess-org-peerjs.vercel.app for a PeerJS id. The caller opens the data channel.

import { fetchPeerId, peerOptions } from "@chaincraft/core/browser";

const id = await fetchPeerId();
const peer = new Peer(id, peerOptions());

What you implement vs what the mesh does

A prototype implements receive. The node wraps the payload, hashes it, and relays it. It does not interpret your application type, and peers may miss a message. Override is_valid only to reject, and add_message only for a consensus protocol.

One node on the default port

With no argument the node binds 0.0.0.0:9735. Local peers still dial 127.0.0.1:9735. It prints ready with the bound address.

python3 -m chaincraft.node

{"event":"ready","addr":"0.0.0.0:9735","impl":"py-chaincraft/1.2.0"}

Same bind after the registry installs: chaincraft-node and chaincraft-ts-node. Pass host:port to override. 127.0.0.1:0 is an ephemeral port.

Three nodes, one language each

One local TCP mesh. Python holds the default port. Rust and TypeScript take the next two and dial Python. Three terminals, after the registry installs above. If a node prints a different ready.addr, connect to that address.

# Terminal 1 — Python
python3 -m chaincraft.node
# ready addr 0.0.0.0:9735

# Terminal 2 — Rust
chaincraft-node 127.0.0.1:9736

# Terminal 3 — TypeScript
chaincraft-ts-node 127.0.0.1:9737
# fallback: node node_modules/@chaincraft/core/dist/node.js 127.0.0.1:9737

On terminal 2 and terminal 3, connect to the default port:

{"cmd":"connect","addr":"127.0.0.1:9735"}

Each prints connected, then hello after ctl.hello. The three processes are now one network on loopback.

Commands: connect, send, ids, quit. Stdout events: ready (addr, impl), hello (peer, addr), connected, sent (id), received (id, type), ids, error. quit stops the process.

Gossip Hello World across the three languages

On the Python node (terminal 1):

{"cmd":"send","type":"app.hello","data":{"message":"Hello, Chaincraft!"}}

Python prints sent with a 64-hex id. After ctl.hello, Rust and TypeScript print received with that same id. On any node:

{"cmd":"ids"}

All three lists contain the same digest. Same content, same canonical JSON, same id. Deduplication stops the relay from looping. Send from Rust or TypeScript the same way; the other two languages receive it.

Two TCP nodes in one program

These open sockets. Node A listens on 9735, node B on 9736. B dials A and gossips app.hello. Both record the same payload id.

Python

Save as hello.py and run python3 hello.py.

import time
from chaincraft.mesh import Mesh
from chaincraft.object import SharedObject


class Hello(SharedObject):
    def receive(self, message):
        print("Received:", message["message"])


hello = Hello()
a = Mesh(on_app=lambda t, d: hello.receive(d) if t == "app.hello" else None)
b = Mesh()
print("listening", a.start("127.0.0.1", 9735))
print("listening", b.start("127.0.0.1", 9736))
b.connect(a.listen_addr)
digest = b.broadcast("app.hello", {"message": "Hello, Chaincraft!"})
time.sleep(0.4)
print(digest)
a.close()
b.close()

Rust

After cargo add chaincraft, save as src/main.rs and run cargo run.

[package]
name = "hello"
version = "0.1.0"
edition = "2021"

[dependencies]
chaincraft = "1.2.0"

use std::sync::Arc;
use std::thread;
use std::time::Duration;

use chaincraft::mesh::Mesh;
use chaincraft::{parse_json, JsonValue, Protocol};

struct Hello;

impl Protocol for Hello {
    fn receive(&mut self, message: &JsonValue) {
        let text = message
            .as_object()
            .and_then(|obj| obj.get("message"))
            .and_then(|value| value.as_str())
            .unwrap_or("");
        println!("Received: {text}");
    }
}

fn main() {
    let a = Mesh::bind("127.0.0.1:9735").unwrap();
    let b = Mesh::bind("127.0.0.1:9736").unwrap();
    a.lock().unwrap().set_on_app(Arc::new(|_t, data| {
        Hello.receive(data);
    }));
    Mesh::connect(&b, "127.0.0.1:9735").unwrap();
    let data = parse_json(r#"{"message":"Hello, Chaincraft!"}"#).unwrap();
    let id = Mesh::broadcast(&b, "app.hello", data).unwrap();
    thread::sleep(Duration::from_millis(400));
    println!("{id}");
}

TypeScript

After npm install @chaincraft/core, save as hello.mjs and run node hello.mjs.

import { Mesh } from "@chaincraft/core";

const a = new Mesh();
const b = new Mesh();
a.onApp = (_t, data) => {
  console.log("Received:", data.message);
};

console.log("listening", await a.start("127.0.0.1", 9735));
console.log("listening", await b.start("127.0.0.1", 9736));
await b.connect(a.listenAddr);
const id = b.broadcast("app.hello", { message: "Hello, Chaincraft!" });
await new Promise((r) => setTimeout(r, 400));
console.log(id);
a.close();
b.close();

More nodes, local or remote

Start further processes on unused ports and connect them to a node that is already listening. Each mesh keeps at most 256 peers. connect allows loopback, RFC1918, public unicast IPv4, localhost, .local, and ordinary DNS names. Unspecified, link-local, multicast, and reserved addresses are refused. Default bind is 0.0.0.0:9735.

python3 -m chaincraft.node
# other host
python3 -m chaincraft.node 0.0.0.0:9736
# then: {"cmd":"connect","addr":"203.0.113.10:9735"}

Next

Attach a ledger or a consensus object and run the live 3×3 interop matrix. The wire rules are SPEC/wire-v1.md. The walkthrough in markdown is hello-world.md.