Optimum Network

https://docs.getoptimum.xyz/docs/
Admin
Optimum Network is a decentralized network that provides fast, resilient messaging for distributed...
Tokens:20,444
Snippets:148
Trust Score:6.2
Update:11 months ago
Show doc for...
Tokens:
Raw
### Copy Environment Example (Bash)

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Copies the example environment file to a new file named .env, which will be used for configuring the Optimum Network deployment. This sets up default configurations that can then be customized.

```bash
cp .env.example .env
```

--------------------------------

### Interact with Proxy via REST API

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Examples for publishing and subscribing to messages using the Proxy's REST API. Also includes an example for establishing a WebSocket connection.

```shell
# Publish
curl -X POST http://localhost:8081/api/v1/publish \
  -H "Content-Type: application/json" \
  -d '{"client_id":"test","topic":"demo","message":"Hello"}'

# Subscribe
curl -X POST http://localhost:8081/api/v1/subscribe \
  -H "Content-Type: application/json" \
  -d '{"client_id":"test","topic":"demo","threshold":0.1}'

# WebSocket
wscat -c "ws://localhost:8081/api/v1/ws?client_id=test"
```

--------------------------------

### Use P2P Client Directly (Subscribe and Publish)

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Examples of using the P2P client for subscribing to and publishing messages directly to a P2P node. Assumes the P2P client executable is available.

```bash
# Subscribe
./p2p-client -mode=subscribe -topic=testtopic --addr=127.0.0.1:33221

# Publish
./p2p-client -mode=publish -topic=testtopic -msg="Hello" --addr=127.0.0.1:33222
```

--------------------------------

### Subscribe and Publish Messages using mump2p-cli (Proxy Mode)

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Demonstrates how to subscribe to and publish messages using the mump2p-cli tool in proxy mode. Requires mump2p-cli to be installed.

```shell
./mump2p subscribe --topic=demo --service-url=http://localhost:8081

```

```shell
./mump2p publish --topic=demo --message="Hello via Proxy" --service-url=http://localhost:8081
```

--------------------------------

### Start P2P Node and Verify Health

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Commands to set an environment variable for the bootstrap peer ID, start the Docker Compose services, and then verify the health of the P2P node.

```shell
export BOOTSTRAP_PEER_ID=<your-peer-id>
docker compose up -d
curl http://localhost:9091/api/v1/health
```

--------------------------------

### Docker Compose Configuration for P2P Node

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

A simplified Docker Compose configuration for setting up a P2P node. This example includes volume mounting for identity and environment variables for cluster and node mode.

```yaml
services:
  p2pnode-1:
    image: 'getoptimum/p2pnode:${P2P_NODE_VERSION-latest}'
    volumes:
      - ./identity:/identity
    environment:
      - CLUSTER_ID=${CLUSTER_ID}
      - NODE_MODE=optimum
      - IDENTITY_DIR=/identity
    ports:
      - "33221:33212"
```

--------------------------------

### POST /api/v1/publish

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Publishes a message to a specified topic via the proxy.

```APIDOC
## POST /api/v1/publish

### Description
Publishes a message to a specified topic via the proxy. Requires 'client_id', 'topic', and 'message' in the request body.

### Method
POST

### Endpoint
/api/v1/publish

### Parameters
#### Request Body
- **client_id** (string) - Required - Identifier for the client.
- **topic** (string) - Required - The topic to publish the message to.
- **message** (string) - Required - The content of the message to publish.

### Request Example
```json
{
  "client_id": "test",
  "topic": "demo",
  "message": "Hello"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., "published").

#### Response Example
```json
{
  "status": "published"
}
```
```

--------------------------------

### Start Docker Compose Network (Shell)

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Starts the Optimum Network services defined in the Docker Compose file in detached mode (-d). It requires setting the BOOTSTRAP_PEER_ID environment variable before execution.

```sh
export BOOTSTRAP_PEER_ID=<your-peer-id>
docker compose up -d
```

--------------------------------

### WS /api/v1/ws

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Establishes a WebSocket connection for real-time message reception via the proxy.

```APIDOC
## WS /api/v1/ws

### Description
Establishes a WebSocket connection for real-time message reception via the proxy. Requires a 'client_id' query parameter.

### Method
WebSocket (WS)

### Endpoint
/api/v1/ws

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Identifier for the client.

### Request Example
`wscat -c "ws://localhost:8081/api/v1/ws?client_id=test"`

### Response
#### Success Response (101 Switching Protocols)
- The connection is upgraded to WebSocket.

#### Response Example
(Messages received over the WebSocket connection will be in the defined message format.)
```

--------------------------------

### Verify Docker Compose Services (Shell)

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Checks the status of the running containers defined in the Docker Compose file. This command helps verify if the Optimum Network services have started successfully.

```sh
docker compose ps
```

--------------------------------

### GET /api/v1/health (P2P Node)

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Retrieves the health status of the P2P node.

```APIDOC
## GET /api/v1/health (P2P Node)

### Description
Retrieves the health status of the P2P node.

### Method
GET

### Endpoint
/api/v1/health

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - The health status of the service (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Create Local Directory Structure (Shell)

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Creates the necessary directories for local Optimum Network deployment, including separate folders for proxy-p2p, direct-p2p, and identity keys. This helps organize your project files.

```sh
mkdir -p ~/optimum-local/{proxy-p2p,direct-p2p,identity}
cd ~/optimum-local
```

--------------------------------

### GET /api/v1/health (Proxy)

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Retrieves the health status of the proxy service.

```APIDOC
## GET /api/v1/health (Proxy)

### Description
Retrieves the health status of the proxy service.

### Method
GET

### Endpoint
/api/v1/health

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - The health status of the service (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### POST /api/v1/subscribe

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Subscribes to a specified topic via the proxy. Messages matching the topic will be received.

```APIDOC
## POST /api/v1/subscribe

### Description
Subscribes to a specified topic via the proxy. Messages matching the topic will be received. Requires 'client_id', 'topic', and 'threshold' in the request body.

### Method
POST

### Endpoint
/api/v1/subscribe

### Parameters
#### Request Body
- **client_id** (string) - Required - Identifier for the client.
- **topic** (string) - Required - The topic to subscribe to.
- **threshold** (number) - Required - A threshold value (e.g., for message filtering or quality of service).

### Request Example
```json
{
  "client_id": "test",
  "topic": "demo",
  "threshold": 0.1
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the subscription (e.g., "subscribed").

#### Response Example
```json
{
  "status": "subscribed"
}
```
```

--------------------------------

### Proxy Service Docker Example (YAML)

Source: https://docs.getoptimum.xyz/docs/guides/03-parameters

Example Docker service configuration for the OptimumProxy. This setup defines ports for HTTP and gRPC APIs, enables/disables authentication, and specifies the P2P nodes to connect to. Useful for client-to-P2P node communication.

```yaml
proxy-1:
  image: 'getoptimum/proxy:${PROXY_VERSION-latest}'
  environment:
    - PROXY_HTTP_PORT=:8080
    - PROXY_GRPC_PORT=:50051
    - CLUSTER_ID=proxy-1
    - ENABLE_AUTH=false
    - LOG_LEVEL=debug
    - P2P_NODES=p2pnode-1:33212,p2pnode-2:33212
```

--------------------------------

### Docker Compose Configuration (YAML)

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Defines the Docker services for running Optimum Network in 'OptimumProxy + mump2p' mode. It includes configurations for a proxy service and a p2pnode service, specifying images, environment variables, ports, and volumes.

```yaml
services:
  proxy-1:
    image: 'getoptimum/proxy:${PROXY_VERSION-latest}'
    environment:
      - CLUSTER_ID=${CLUSTER_ID}
      - P2P_NODES=p2pnode-1:33212,p2pnode-2:33212
    ports:
      - "8081:8080"
      - "50051:50051"

  p2pnode-1:
    image: 'getoptimum/p2pnode:${P2P_NODE_VERSION-latest}'
    volumes:
      - ./identity:/identity
    environment:
      - CLUSTER_ID=${CLUSTER_ID}
      - NODE_MODE=optimum
      - IDENTITY_DIR=/identity
```

--------------------------------

### Check Node Reachability with Netcat

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Troubleshooting command to check if the proxy container can reach a P2P node on its listening port. This helps diagnose network connectivity issues between containers.

```shell
docker compose exec proxy sh -lc 'nc -zv p2pnode-1 33212'
```

--------------------------------

### Generate Identity with Script (Bash)

Source: https://docs.getoptimum.xyz/docs/guides/05-faq-glossary

This script fetches and executes the identity generation script from the GitHub repository. It automatically generates `p2p.key` and exports the `BOOTSTRAP_PEER_ID` environment variable, simplifying the setup process for Dockerized environments.

```bash
curl -sSL https://raw.githubusercontent.com/getoptimum/optimum-dev-setup-guide/main/script/generate-identity.sh | bash
```

--------------------------------

### Generate Bootstrap Identity (Bash)

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Generates a unique P2P identity required for node discovery in the Optimum Network. This command typically uses a Makefile target to create an identity file (e.g., ./identity/p2p.key).

```bash
make generate-identity
```

--------------------------------

### Stop Docker Compose Services

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Commands to stop and remove Docker containers, networks, and volumes created by Docker Compose. The first command stops services, while the second performs a full reset.

```shell
docker compose down

docker compose down -v --rmi local
```

--------------------------------

### Check Health Status with Curl

Source: https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker

Use curl to check the health status of the proxy and P2P nodes. This is useful for verifying that services are running and accessible.

```shell
curl http://localhost:8081/api/v1/health  # Proxy
curl http://localhost:9091/api/v1/health  # P2P node
```

--------------------------------

### mump2p (RLNC) Mode Docker Service Example (YAML)

Source: https://docs.getoptimum.xyz/docs/guides/03-parameters

Example Docker service configuration for mump2p nodes running in 'optimum' mode. It specifies environment variables for RLNC-specific parameters like shard factor and threshold, alongside general cluster and port settings.

```yaml
p2pnode-1:
  image: 'getoptimum/p2pnode:${P2P_NODE_VERSION-latest}'
  environment:
    - NODE_MODE=optimum
    - CLUSTER_ID=${CLUSTER_ID}
    - OPTIMUM_PORT=7070
    - OPTIMUM_MESH_TARGET=6
    - OPTIMUM_SHARD_FACTOR=4
    - OPTIMUM_THRESHOLD=0.75
```

--------------------------------

### GossipSub Mode Docker Service Example (YAML)

Source: https://docs.getoptimum.xyz/docs/guides/03-parameters

Example Docker service configuration for mump2p nodes running in 'gossipsub' mode. It includes environment variables for standard libp2p gossip parameters such as message size and mesh target, along with bootstrap peer configuration.

```yaml
p2pnode-1:
  image: 'getoptimum/p2pnode:${P2P_NODE_VERSION-latest}'
  environment:
    - NODE_MODE=gossipsub
    - LOG_LEVEL=debug
    - CLUSTER_ID=p2pnode-1
    - GOSSIPSUB_PORT=6060
    - GOSSIPSUB_MAX_MSG_SIZE=1048576
    - GOSSIPSUB_MESH_TARGET=6
    - GOSSIPSUB_MESH_MIN=4
    - GOSSIPSUB_MESH_MAX=12
    - BOOTSTRAP_PEERS=/ip4/172.28.0.12/tcp/6060/p2p/${BOOTSTRAP_PEER_ID}
```

--------------------------------

### Basic Subscription Output - Bash

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

The output of a basic subscription, including claim details, subscription request confirmation, and WebSocket connection status. It indicates the client is now listening for messages.

```bash
claims is &{google-oauth2|100677750055416883405 2025-08-17 13:15:07 +0530 IST 2025-08-18 13:15:07 +0530 IST true 4194304 1000 8 5368709120 google-oauth2|100677750055416883405 1755416706719}
claims is google-oauth2|100677750055416883405
Sending HTTP POST subscription request...
HTTP POST subscription successful: {"status":"subscribed","topic":"demo"}
Opening WebSocket connection...
Listening for messages on topic 'demo'... Press Ctrl+C to exit
```

--------------------------------

### Basic Subscription - Shell

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Subscribes to a specified topic using the mump2p CLI. This is the fundamental command for receiving messages from a topic.

```shell
./mump2p subscribe --topic=demo
```

--------------------------------

### Subscription with Persistence Output - Bash

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Output indicating that messages are being persisted to a log file. It includes confirmation of the persistence path and the successful subscription.

```bash
Persisting data to: /path/to/messages.log
claims is &{google-oauth2|100677750055416883405 2025-08-17 13:15:07 +0530 IST 2025-08-18 13:15:07 +0530 IST true 4194304 1000 8 5368709120 google-oauth2|100677750055416883405 1755416706719}
claims is google-oauth2|100677750055416883405
Sending HTTP POST subscription request...
HTTP POST subscription successful: {"status":"subscribed","topic":"demo"}
Opening WebSocket connection...
Listening for messages on topic 'demo'... Press Ctrl+C to exit
```

--------------------------------

### Test Proxy Health Endpoint (Bash)

Source: https://docs.getoptimum.xyz/docs/guides/05-faq-glossary

This command sends an HTTP GET request to the health check endpoint of the Optimum proxy service. It's used to verify basic network connectivity and ensure the proxy is running and responsive.

```bash
curl http://localhost:8080/health
```

--------------------------------

### Usage and Limits Output - Bash

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Detailed output of the mump2p usage command, showing per-hour and per-second publish limits, data used against quota, time to next reset, and last publish timestamp.

```bash
  Publish (hour):     0 / 1000
  Publish (second):   0 / 8
  Data Used:          0.0000 MB / 5120.0000 MB
  Next Reset:         18 Aug 25 13:15 IST (24h0m0s from now)
  Last Publish:       07 Aug 25 06:33 -0700
```

--------------------------------

### Check Usage and Limits - Shell

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Displays current usage statistics for publishing, data consumption, and the time until the next quota reset. Also shows token expiry information.

```shell
./mump2p usage
```

--------------------------------

### gRPC Subscription - Shell

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Subscribes to a topic using gRPC for high-performance, low-latency message streaming. This is suitable for demanding real-time applications.

```shell
./mump2p subscribe --topic=demo --grpc
```

--------------------------------

### List Active Topics - Shell

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Lists all topics to which the current user is subscribed. This command helps in managing subscriptions across different topics.

```shell
./mump2p list-topics
```

--------------------------------

### Publish File Message Output - Bash

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Confirms that a file's content has been successfully published as a message to the specified topic. Shows the filename and status.

```bash
✅ Published sample-data.json
{"status":"published","topic":"demo"}
```

--------------------------------

### Webhook Subscription with Custom Schema - Shell

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Subscribes to a topic and forwards messages to a webhook, utilizing custom JSON schema templates for different platforms like Discord, Slack, or custom formats.

```shell
# Discord
./mump2p subscribe --topic=alerts --webhook="https://discord.com/api/webhooks/..." --webhook-schema='{"content":"{{.Message}}"}'

# Slack
./mump2p subscribe --topic=notifications --webhook="https://hooks.slack.com/services/..." --webhook-schema='{"text":"{{.Message}}"}'

# Custom JSON with metadata
./mump2p subscribe --topic=logs --webhook="https://your-server.com/webhook" --webhook-schema='{"message":"{{.Message}}","timestamp":"{{.Timestamp}}","topic":"{{.Topic}}"}'
```

--------------------------------

### Subscription with Persistence - Shell

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Subscribes to a topic and persists all received messages to a specified local file path. This is useful for logging or offline analysis.

```shell
./mump2p subscribe --topic=demo --persist=/path/to/
```

--------------------------------

### Persisted Message Format - Bash

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Shows the format of messages when persisted locally. Each entry includes a timestamp and the message content.

```bash
[2025-08-17T13:19:08+05:30] Testing persistence!
```

--------------------------------

### mump2p Mode Environment Variables Configuration (YAML)

Source: https://docs.getoptimum.xyz/docs/guides/03-parameters

This snippet shows the environment variables for the 'mump2p' mode of the getoptimum_xyz project, configured using YAML. It includes settings for node mode, logging, cluster ID, ports, identity directory, and specific parameters for the 'optimum' protocol like message size, mesh configuration, and redundancy settings. This is a quick-start, copy-paste-ready configuration.

```yaml
environment:
  - NODE_MODE=optimum
  - LOG_LEVEL=production
  - CLUSTER_ID=my-cluster
  - SIDECAR_PORT=33212
  - API_PORT=8081
  - IDENTITY_DIR=/identity
  - OPTIMUM_PORT=7070
  - OPTIMUM_MAX_MSG_SIZE=1048576
  - OPTIMUM_RANDOM_MSG_SIZE=512
  - OPTIMUM_MESH_TARGET=6
  - OPTIMUM_MESH_MIN=4
  - OPTIMUM_MESH_MAX=12
  - OPTIMUM_SHARD_FACTOR=4
  - OPTIMUM_SHARD_MULT=1.5
  - OPTIMUM_THRESHOLD=0.75
  - BOOTSTRAP_PEERS=""
```

--------------------------------

### Check Running Docker Containers (Bash)

Source: https://docs.getoptimum.xyz/docs/guides/05-faq-glossary

This command lists all currently running Docker containers. It's a basic troubleshooting step to verify that the necessary Optimum project containers (like proxy and p2pnode) are active and running as expected.

```bash
docker ps
```

--------------------------------

### Webhook Subscription - Shell

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Subscribes to a topic and forwards received messages to a specified webhook URL. This enables integration with external services.

```shell
./mump2p subscribe --topic=demo --webhook=https://your-server.com/webhook
```

--------------------------------

### List Docker Networks (Bash)

Source: https://docs.getoptimum.xyz/docs/guides/05-faq-glossary

This command lists all available Docker networks on the host machine. It is useful for diagnosing network-related problems, such as connectivity issues between containers or conflicts with the host network.

```bash
docker network ls
```

--------------------------------

### gRPC Subscription Output - Bash

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Output from a gRPC subscription, confirming the subscription and indicating that messages are being received via gRPC. It includes claim details and connection status.

```bash
claims is &{google-oauth2|100677750055416883405 2025-08-21 16:01:29 +0530 IST 2025-08-22 16:01:29 +0530 IST true 4194304 1000 8 5368709120 google-oauth2|100677750055416883405 1755772288994}
claims is google-oauth2|100677750055416883405
Sending HTTP POST subscription request...
HTTP POST subscription successful: {"client":"google-oauth2|100677750055416883405","status":"subscribed"}
Listening for messages on topic 'demo' via gRPC... Press Ctrl+C to exit
```

--------------------------------

### Check Current User Authentication (Bash)

Source: https://docs.getoptimum.xyz/docs/guides/05-faq-glossary

This command verifies the current authentication status for the mump2p CLI. It helps in diagnosing authentication-related issues by confirming if the user is properly logged in or authenticated with the Optimum services.

```bash
mump2p whoami
```

--------------------------------

### Inspect Docker Network (Bash)

Source: https://docs.getoptimum.xyz/docs/guides/05-faq-glossary

This command provides detailed information about a specific Docker network, including connected containers and IP addresses. It aids in troubleshooting network configuration and connectivity problems within the Optimum project's Docker environment.

```bash
docker network inspect
```

--------------------------------

### Set Authentication Path - Bash

Source: https://docs.getoptimum.xyz/docs/guides/01-getting-started-cli

Sets the environment variable MUMP2P_AUTH_PATH to specify the location of the authentication token file. This is a prerequisite for most mump2p operations.

```bash
export MUMP2P_AUTH_PATH="/opt/mump2p/auth/token.yml"
```
Tokens:
Raw