Merge branch 'topology-foundation:main' into main

.github/workflows/build-docker-image.yml → .github/workflows/docker.yml

@@ -2,6 +2,8 @@ name: Build Docker Image
 on:
   release:
     types: [published]
+permissions:
+  packages: write
 env:
   IMAGE: ghcr.io/${{ github.repository }}
 jobs:
@@ -90,7 +92,7 @@ jobs:
         working-directory: /tmp/digests
         run: |
           docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
-            $(printf '${{ env.IMAGE }}@sha256:%s ' *)          
+            $(printf '${{ env.IMAGE }}@sha256:%s ' *)
       - name: Inspect image
         run: |
           docker buildx imagetools inspect ${{ env.IMAGE }}:${{ steps.meta.outputs.version }}

.github/workflows/docs.yml

@@ -9,16 +9,14 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Set up Node
-        uses: actions/setup-node@v1
-        with:
-          node-version: 16
+        uses: actions/setup-node@v4
       - run: |
-          yarn
-          yarn docs
+          cd packages/node && yarn && yarn build
+          cd ../.. && yarn docs
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
         with:
           path: ./docs
   deploy:
@@ -30,4 +28,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

README.md

@@ -1,2 +1,43 @@
-# ts-topology
-The official TypeScript implementation of Topology Protocol
+<div align="center">
+  <img src="https://avatars.githubusercontent.com/u/157637200" height="128">
+  <br />
+  <h1>The TypeScript implementation of the Topology Protocol</h1>
+</div>
+
+<div align="center">
+
+![Version](https://img.shields.io/github/package-json/v/topology-foundation/ts-topology)
+[![Docs](https://img.shields.io/badge/docs-page-blue)](https://topology-foundation.github.io/ts-topology/)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/topology-foundation/ts-topology/blob/main/LICENSE)
+[![Issues](https://img.shields.io/badge/issues-report-red)](https://github.com/topology-foundation/ts-topology/issues)
+[![Pull Requests](https://img.shields.io/badge/pull_requests-open-orange)](https://github.com/topology-foundation/ts-topology/pulls)
+
+[![Website](https://img.shields.io/badge/Website-866678)](https://topology.gg)
+[![GitHub](https://img.shields.io/badge/GitHub-ffffff)](https://github.com/topology-foundation)
+[![X](https://img.shields.io/badge/X-000000)](https://x.com/topology_gg)
+[![Telegram](https://img.shields.io/badge/Telegram-24A1DE)](https://t.me/topologyfrens)
+[![Discord](https://img.shields.io/badge/Discord-7289da)](https://discord.gg/GUDGzBP5mn)
+</div>
+
+# Overview
+
+This is the official TypeScript implementation of the Topology Protocol. The Topology Protocol is a local-first decentralized protocol for real-time applications. It introduces a new concept for Conflict-free Replicated Objects (CRO), that are built on top of libp2p and composed of CRDTs.
+
+# Specifications
+
+The specifications of the Topology Protocol are shared across different client implementations and can be found in the [specs repository](https://github.com/topology-foundation/specs). Currently the specifications are starting to be written based on this implementation.
+
+# Packages
+
+This repository is a monorepo that contains the following packages:
+
+| Package | Description                                      |
+|---------|--------------------------------------------------|
+| crdt    | CRDT implementations intended to use as builtins |
+| network | Network middleware to abstract libp2p            |
+| node    | Topology Node library and CLI                    |
+| object  | CRO objects structure implementation             |
+
+# Examples
+
+All the examples are located in the `examples` directory. Currently, there is only one example, which is a simple canvas where you can paint pixels. You can also look into the [counter-splash](https://github.com/topology-foundation/counter-splash) (demo for EthCC 2024) repository for a more complex example.

docker-compose.yml

@@ -19,7 +19,7 @@ services:
       dockerfile: Dockerfile
     ports:
       - 50000:50000
-    command: relay
+    command: -m relay
 
 volumes:
   ssl_data:

examples/canvas/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-topology-examples-canvas",
-  "version": "0.0.21",
+  "version": "0.0.22-2",
   "license": "MIT",
   "scripts": {
     "build": "webpack",
@@ -9,10 +9,10 @@
     "start": "ts-node ./src/index.ts"
   },
   "dependencies": {
-    "@topology-foundation/crdt": "0.0.21",
-    "@topology-foundation/network": "0.0.21",
-    "@topology-foundation/node": "0.0.21",
-    "@topology-foundation/object": "0.0.21",
+    "@topology-foundation/crdt": "0.0.22-2",
+    "@topology-foundation/network": "0.0.22-2",
+    "@topology-foundation/node": "0.0.22-2",
+    "@topology-foundation/object": "0.0.22-2",
     "crypto-browserify": "^3.12.0",
     "process": "^0.11.10",
     "stream-browserify": "^3.0.0",

package.json

@@ -1,7 +1,7 @@
 {
   "name": "ts-topology",
   "description": "The official TypeScript implementation of Topology Protocol",
-  "version": "0.0.21",
+  "version": "0.0.22-2",
   "license": "MIT",
   "homepage": "https://topology.gg/",
   "repository": {
@@ -19,10 +19,10 @@
   "devDependencies": {
     "@release-it-plugins/workspaces": "^4.2.0",
     "@types/node": "^20.14.10",
-    "release-it": "^17.4.1",
+    "release-it": "^17.6.0",
     "typedoc": "^0.26.4",
     "typescript": "^5.4.5",
-    "vitest": "^2.0.2"
+    "vitest": "^2.0.3"
   },
   "workspaces": [
     "packages/*",

packages/crdt/README.md

@@ -0,0 +1,37 @@
+# Conflict-free Replicated Data Types (CRDTs)
+
+This package contains the CRDT implementations intended to use as builtins for the Topology Protocol.
+
+## Usage
+
+This package is intended to be used as a dependency for the Topology Protocol. However, you can use it as a standalone package. For that, you can install it using:
+
+```bash
+# yarn
+yarn add @topology-foundation/crdt
+
+# npm
+npm install @topology-foundation/crdt
+```
+
+### Build
+
+To build the package, you can run:
+
+```bash
+yarn build
+```
+
+### Tests
+
+To run the tests, you can run:
+
+```bash
+yarn test
+```
+
+## CRDTs Implementations
+- [x] G-Counter
+- [x] PN-Counter
+- [x] G-Set
+- [x] 2P-Set

packages/crdt/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topology-foundation/crdt",
-  "version": "0.0.21",
+  "version": "0.0.22-2",
   "license": "MIT",
   "repository": {
     "type": "git",

packages/crdt/typedoc.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://typedoc.org/schema.json",
   "includeVersion": true,
-  "entryPoints": ["src/index.ts"]
+  "entryPoints": ["src/index.ts"],
+  "readme": "README.md"
 }

packages/network/README.md

@@ -0,0 +1,33 @@
+# Topology Network Stack
+
+This package contains the network middleware to abstract libp2p for the Topology Protocol.
+
+To do so, we define a `TopologyNetworkNode` where we can pass the configs that we want and it "magically" configures libp2p and gives connectivity to the Topology Network.
+
+## Usage
+
+This package is intended to be used as a dependency for the Topology Protocol. However, you can use it as a standalone package. For that, you can install it using:
+
+```bash
+# yarn
+yarn add @topology-foundation/network
+
+# npm
+npm install @topology-foundation/network
+```
+
+### Build
+
+To build the package, you can run:
+
+```bash
+yarn build
+```
+
+### Tests
+
+To run the tests, you can run:
+
+```bash
+yarn test
+```

packages/network/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topology-foundation/network",
-  "version": "0.0.21",
+  "version": "0.0.22-2",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -36,17 +36,17 @@
     "@chainsafe/libp2p-yamux": "^6.0.2",
     "@libp2p/autonat": "^1.0.0",
     "@libp2p/bootstrap": "^10.1.0",
-    "@libp2p/circuit-relay-v2": "^1.0.24",
+    "@libp2p/circuit-relay-v2": "^1.1.2",
     "@libp2p/dcutr": "^1.1.0",
     "@libp2p/identify": "^2.0.2",
     "@libp2p/interface-pubsub": "^4.0.1",
     "@libp2p/mdns": "^10.1.1",
     "@libp2p/pubsub-peer-discovery": "^10.0.2",
-    "@libp2p/webrtc": "^4.1.1",
+    "@libp2p/webrtc": "^4.1.2",
     "@libp2p/websockets": "^8.1.1",
     "@libp2p/webtransport": "^4.1.1",
     "@multiformats/multiaddr": "^12.3.0",
     "it-pipe": "^3.0.1",
-    "libp2p": "^1.6.0"
+    "libp2p": "^1.8.1"
   }
 }

packages/network/src/node.ts

@@ -18,7 +18,11 @@ import { stringToStream } from "./stream.js";
 import { bootstrap } from "@libp2p/bootstrap";
 import { webTransport } from "@libp2p/webtransport";
 
-export interface TopologyNetworkNodeConfig {}
+// snake_casing to match the JSON config
+export interface TopologyNetworkNodeConfig {
+  addresses: string[];
+  bootstrap_peers: string[];
+}
 
 export class TopologyNetworkNode {
   private _config?: TopologyNetworkNodeConfig;
@@ -34,7 +38,7 @@ export class TopologyNetworkNode {
   async start() {
     this._node = await createLibp2p({
       addresses: {
-        listen: ["/webrtc"],
+        listen: this._config ? this._config.addresses : ["/webrtc"],
       },
       connectionEncryption: [noise()],
       connectionGater: {
@@ -48,9 +52,11 @@ export class TopologyNetworkNode {
           topics: ["topology::discovery"],
         }),
         bootstrap({
-          list: [
-            "/dns4/relay.droak.sh/tcp/443/wss/p2p/Qma3GsJmB47xYuyahPZPSadh1avvxfyYQwk8R3UnFrQ6aP",
-          ],
+          list: this._config
+            ? this._config.bootstrap_peers
+            : [
+                "/dns4/relay.droak.sh/tcp/443/wss/p2p/Qma3GsJmB47xYuyahPZPSadh1avvxfyYQwk8R3UnFrQ6aP",
+              ],
         }),
       ],
       services: {

packages/network/src/relay.ts

@@ -10,17 +10,20 @@ import { createLibp2p } from "libp2p";
 
 import relayerJson from "./peer-id-relayer.js";
 import { autoNAT } from "@libp2p/autonat";
+import { TopologyNetworkNodeConfig } from "./node.js";
 
 // TODO:
 //  - remove the peer-id-relayer in favor of static configs
 //  - create a "relay" mode that can be activated in the main node.ts logic
 //  - improve the circuit-relay setup
-export const createRelayNode = async () => {
+export const createRelayNode = async (config?: TopologyNetworkNodeConfig) => {
   const idRelayer = await createFromJSON(relayerJson);
   const node = await createLibp2p({
     peerId: idRelayer,
     addresses: {
-      listen: ["/ip4/0.0.0.0/tcp/50000/ws", "/ip4/0.0.0.0/tcp/50001"],
+      listen: config
+        ? config.addresses
+        : ["/ip4/0.0.0.0/tcp/50000/ws", "/ip4/0.0.0.0/tcp/50001"],
     },
     connectionEncryption: [noise()],
     peerDiscovery: [

packages/network/typedoc.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://typedoc.org/schema.json",
   "includeVersion": true,
-  "entryPoints": ["src/index.ts"]
+  "entryPoints": ["src/index.ts"],
+  "readme": "README.md"
 }

packages/node/Dockerfile

@@ -3,6 +3,7 @@ FROM node:22.3-bookworm-slim
 WORKDIR /node
 COPY . .
 
+RUN yarn
 RUN chmod +x /node/entrypoint.sh
 
 ENTRYPOINT ["/bin/bash", "/node/entrypoint.sh"]

packages/node/README.md

@@ -0,0 +1,50 @@
+# Topology Node
+
+This package provides the implementation of a Topology Node, which is a node in a network that can be connected to other nodes and exchange messages with them. The Topology Node is the entrypoint for interacting with the Topology Protocol in the Topology Network.
+
+## Usage
+
+Topology Node can be used using the CLI or integrated into an existing application.
+
+### CLI
+
+The CLI provides a simple way to start a Topology Node and connect it to other nodes in the network. It can be installed globally using:
+
+```bash
+# yarn
+yarn global add @topology-foundation/node
+
+# npm
+npm install -g @topology-foundation/node
+```
+
+> This part is a lie, the cli is being developed.
+
+For more information on what are the commands available, run:
+
+```bash
+topology-node --help
+```
+
+### Integration
+
+To integrate the Topology Node into an existing application, you can install it using:
+
+```bash
+# yarn
+yarn add @topology-foundation/node
+
+# npm
+npm install @topology-foundation/node
+```
+
+Then, you can import the Topology Node class and create a new instance:
+
+```javascript
+import { TopologyNode } from '@topology-foundation/node';
+
+const node = new TopologyNode();
+
+// Start the node
+node.start();
+```

packages/node/configs/node.json

@@ -0,0 +1,8 @@
+{
+  "network_config": {
+    "addresses": ["/webrtc"],
+    "bootstrap_peers": [
+      "/dns4/relay.droak.sh/tcp/443/wss/p2p/Qma3GsJmB47xYuyahPZPSadh1avvxfyYQwk8R3UnFrQ6aP"
+    ]
+  }
+}