A topic is 32 bytes that peers agree on, usually a hash such as
sha256("kolo chat example"). It names what the peers want to share: a
chat room, a document, a log. Kolo does not keep a list of topics, and the
bytes mean nothing to it.
Announce and look up
A lookup, step by step
This example uses 8-bit IDs. Real IDs have 256 bits, the table keeps 20 servers per bucket and up to 10 queries run at once.
- Your routing table gives the servers it knows closest to the topic: here A, B and C. Distance is the XOR of the two IDs.
- You send LOOKUP to them at once. Each reply carries servers closer to the topic, a token and any records.
- C knows D and E, which are closer. You ask them as soon as the reply arrives: there are no fixed rounds.
- E knows F and G, closer still. The list is sorted by distance after every reply.
- The walk stops when the 20 closest servers it knows have answered or timed out, or after 100 queries. Each record is signed by the peer that announced it, and the signature is checked.
- A lookup returns records, not connections. Connect is a separate call, through a server that stored the record.
Connecting through two NATs
Both peers sit behind home routers. A bootstrap node on the internet puts them in touch; the packets then flow directly.
- A and B each announce a signed record on the topic to a bootstrap node, each from behind its own NAT.
- A looks the topic up. The reply carries B's signed record, with its public key and its address, and the node that stored it.
- A sends CONNECT to that node, which passes the request on to B. Neither peer can reach the other yet: both NATs only let answers in.
- Both send PUNCH packets to each other at the same time. Each NAT sees its own peer's packet go out and opens a mapping, so the other's packets are let in.
- The direct path is up: packets flow between A and B without the node. kolo-secure then proves both keys on the connection.
kolo-dht is a distributed hash table spread over the peers that run as servers, such as kolo-node.
- To be found, a peer announces the topic: it stores a record, signed with its key, at each of the up to 20 closest servers that answered its lookup of the topic; one stored copy is enough. It refreshes the record every 15 seconds. A server drops a record 20 minutes after its last refresh.
- To find others, a peer looks the topic up. It gets back the signed records of the peers on it, checks each signature, and can then connect to them. The server that stored a record helps the two peers open a direct path through their NATs.
kolo-swarm does both for you: Join announces
the topic, looks it up, or both, and keeps connections to the peers it
finds.
Large groups are a planned direction, with two planned libraries and no code yet: kolo-gossip, to pass small messages from member to member of a topic without a relay, after the GossipSub specification (version 1.1 with the IDONTWANT rule of version 1.2), and kolo-mls, to encrypt a group end to end by MLS (RFC 9420). See Planned on the roadmap.
A new peer needs a first address
A peer joins the DHT through one or more known servers, the bootstrap addresses. If you give it none, it uses the two public entry nodes that Ciranda runs, built into kolo-dht: free, with no uptime guarantee while Kolo is a beta. For a network of your own, you give it your addresses, and the public ones are not used. Running a few kolo-node servers on hosts with a public IPv4 address is the usual way.
Good to know
- The servers on the path see which addresses announce and look up a topic.
- Kolo is IPv4 only. IPv6 addresses are refused.