> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/decentralization-manager/get-started/connect-peers.md).

# Connect peers

[Overview](/decentralization-manager/overview.md) · [Prerequisites](/decentralization-manager/get-started/prerequisites.md) · [Run locally](/decentralization-manager/get-started/run-locally.md)

### Outcome

Exchange peer records between Decentralization Manager nodes. Then verify that every node reaches every other node before you start a multi-party workflow.

### Before you start

Each organization needs:

* A running Decentralization Manager node. All nodes of a Decentralized Party must run the same release.
* A persistent data directory. The node keeps its Noise key and its database in this directory, as `data/noise.key` and `data/decpm.db`.
* `DECPM_PUBLIC_ADDRESS` set to the host name or IP address that the other nodes use to reach this node.
* The Noise port open to the other nodes over raw TCP. `DECPM_NOISE_PORT` sets the port. The default is `9000`.
* An operator account on the node. When `DECPM_ADMIN_ROLE` is set, only that role can save peers.
* An authenticated channel to exchange peer records with the other operators.

Connecting peers does not create a Decentralized Party. Later workflows send their messages over these peer connections.

{% hint style="warning" %}
Peers connect to the Noise port over raw TCP. Do not put a TLS-terminating proxy in front of that port. See [Production deployment](/decentralization-manager/get-started/production-deployment.md) for the network setup.
{% endhint %}

### Peer record

A peer record is one CSV line with these columns:

```
participant_id,name,address,port,public_key,party
```

| Column           | Content                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| `participant_id` | The Canton participant ID of the node, in the form `<prefix>::<68 hex characters>`.               |
| `name`           | A display name. Any text works.                                                                   |
| `address`        | The host name or IP address that peers connect to. The node takes it from `DECPM_PUBLIC_ADDRESS`. |
| `port`           | The Noise port of the node.                                                                       |
| `public_key`     | The Noise public key of the node, as a hex-encoded secp256k1 key.                                 |
| `party`          | Optional. The column can be empty.                                                                |

A node accepts a Noise handshake only from a participant ID in its own peer list. The node derives the pre-shared key for the handshake from the stored public key of that peer. A wrong public key therefore makes the handshake fail.

Treat the participant ID and the public key as security-sensitive configuration. Verify both through the authenticated channel.

### 1. Check your own node

1. Open **Configuration**.
2. In the node card, under **Identity**, note the **Participant ID**.
3. Under **Peers:**, find the row marked **(You)**. A person icon marks this row in the **Status** column. The tooltip of the icon reads "This is your node".
4. Confirm that the address in that row is your public address. An address such as `0.0.0.0` means that `DECPM_PUBLIC_ADDRESS` is not set.

### 2. Copy your peer record

Under **Peers:**, click **Share my data**. Decentralization Manager copies your peer record to the clipboard as one CSV line.

To send several peer records in one file, click **Export CSV**. Select the rows, then click the **Download** button. The file starts with a header row and includes your own node.

### 3. Exchange records out of band

Send your peer record to each operator through the authenticated channel. Receive the peer record of each operator the same way.

Do not accept a peer record that arrives through an unauthenticated chat, a public issue, or a forwarded message.

### 4. Add the peer

1. Copy the peer record of the other node to your clipboard.
2. Under **Peers:**, click the pencil icon (**Edit peers**).
3. Click **Paste from Clipboard**. Decentralization Manager adds one row for each valid CSV line. It skips each invalid line and shows the reason.
4. Compare the participant ID, address, port, and public key with the record that the operator sent.
5. Click **Save**.

To add peers from a file, click **Import CSV** and then **Choose CSV file**. The dialog marks each row **New**, **Update**, or **Unchanged**. Clear the rows that you do not want, then click the **Import** button. The import keeps the existing peers that the file does not list.

Repeat these steps on both sides. A node accepts handshakes only from the peers in its own list. A one-sided entry therefore leaves the connection broken.

### Full mesh

To create a Decentralized Party, every selected node must list every other selected node. Before onboarding starts, the coordinator asks each selected peer for its peer list. When an entry is missing, the coordinator does not start the workflow run. The **Create a decentralized party** dialog then shows the gaps:

* **Coordinator can't reach these peers:** The coordinator cannot query these peers. Fix the entry for each peer on the coordinator, or check that the peer is online.
* **Update network configs:** A selected peer does not list another selected peer. On the named node, add each listed peer.

The API returns HTTP 422 with a `missing_edges` array. Each entry holds `from`, `to`, and `kind`. The `kind` is `unreachable_from_coordinator` or `mesh_hole`.

Set up the full mesh for every Decentralized Party, even when one workflow run needs fewer connections. A later workflow run can have a different coordinator.

### 5. Verify connectivity

The **Status** column of the peers table shows one dot for each peer. Hold the pointer over a dot to read the status.

| Status                                                      | Meaning                                                                    | Next action                                                                                               |
| ----------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Connected via Noise protocol                                | The handshake works. The tooltip also shows the round-trip time.           | None.                                                                                                     |
| Cannot reach peer (TCP connection failed)                   | The node cannot open a TCP connection to the address and port of the peer. | Check the address, the port, the firewall, the load balancer, DNS, and the peer process.                  |
| Noise handshake failed - check if the public key is correct | The TCP connection opens, but the handshake fails.                         | Compare the public key with the peer record. Confirm that the peer lists your node with your current key. |
| This is your node                                           | The row is your own node. A person icon replaces the dot.                  | None.                                                                                                     |

Also check the **Version** column. It must show the same release on every node. A coordinator invites only peers that use the same Noise wire version and report version `0.1.9` or later. All nodes of a Decentralized Party must still run the same release.

On both sides, confirm that the participant ID and the public key of each peer match the record from its operator.

### Manage peers with the API

Send an operator access token in the `Authorization` header. See [Authentication and operator roles](/decentralization-manager/operations-and-reference/authentication-and-operator-roles.md).

`POST /network-config` replaces the whole peer list. Send every peer in the body, not only the new one. When `DECPM_ADMIN_ROLE` is set, the call requires that role.

```bash
# Read the current peer list
curl -sS http://localhost:8080/network-config \
  -H "Authorization: Bearer $TOKEN"

# Replace the peer list
curl -sS -X POST http://localhost:8080/network-config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "participant_id": "participant2::1220...",
      "name": "Participant 2",
      "address": "peer2.example.com",
      "port": 9000,
      "public_key": "02ef34ab...",
      "party": null
    }
  ]'
```

| Endpoint                   | Returns                                                          |
| -------------------------- | ---------------------------------------------------------------- |
| `GET /keys/status`         | The Noise public key of this node.                               |
| `GET /node-config`         | The participant ID, public address, and Noise port of this node. |
| `GET /participants-status` | The connection status, latency, and version of each peer.        |

The node rejects a peer with an invalid Noise public key with HTTP 400. A saved change applies to the next handshake. The node does not need a restart.

### Replace a peer record safely

A node creates a new Noise key at start when `data/noise.key` is missing. The other nodes then reject its handshakes until they store the new public key. To replace a peer record:

1. Wait until no workflow run involves the affected peer.
2. Get the new peer record through the authenticated channel.
3. Compare the participant ID, address, and public key with the operator.
4. Replace the old record on every node that lists the peer.
5. Verify the connection on both sides before you start new workflow runs.

{% hint style="info" %}
Do not delete the Noise key as a routine troubleshooting step. Every other node identifies your node by its public key. A new key forces every operator to update their peer list.
{% endhint %}

### Troubleshooting

| Symptom                                                       | Check                                                                            | Next action                                                                                                                                                       |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status reads "Cannot reach peer (TCP connection failed)"      | Address, port, firewall, load balancer, DNS, and the peer process                | Test the TCP connection from the network of the peer.                                                                                                             |
| Status reads "Noise handshake failed"                         | The stored public key, and whether the peer lists your node                      | Exchange the peer records again through the authenticated channel.                                                                                                |
| Logs show "Noise protocol version mismatch"                   | The release on each node                                                         | Upgrade every node to the same release. See [Backup, recovery, and upgrades](/decentralization-manager/operations-and-reference/backup-recovery-and-upgrades.md). |
| Onboarding does not start, and the dialog lists missing peers | The **Coordinator can't reach these peers** and **Update network configs** lists | Add each missing peer on the named node, then start again.                                                                                                        |
| Your own row shows `0.0.0.0`                                  | `DECPM_PUBLIC_ADDRESS`                                                           | Set the variable, then restart the node.                                                                                                                          |
| Handshakes fail after a restart                               | The persistent data directory and the Noise key                                  | Restore the intended volume before you replace peer records.                                                                                                      |
| **Paste from Clipboard** shows an error                       | The CSV line                                                                     | Ask the operator for the line again. A valid line has 5 or 6 columns.                                                                                             |

### Technical sources

* [Exchange peer details](https://github.com/DLC-link/decentralization-manager/blob/main/docs/ADDING_A_MEMBER_TO_A_DECENTRALIZED_PARTY.md#exchange-peer-details)
* [Peers UI](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/frontend/src/components/NetworkConfigAccordion.tsx)
* [Peer CSV format](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/frontend/src/peerCsv.ts)
* [Peer configuration API](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/src/server/handlers/config.rs)
* [Onboarding mesh check and peer version gate](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/src/server/handlers/workflows.rs)
* [Noise wire version](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/src/noise/mod.rs)
* [Architecture and peer communication](https://github.com/DLC-link/decentralization-manager/blob/main/docs/ARCHITECTURE.md)
* [Deployment guide, Noise port exposure](https://github.com/DLC-link/decentralization-manager/blob/main/docs/DEPLOYMENT_GUIDE.md)

### Related pages

* [Create a Decentralized Party](/decentralization-manager/get-started/create-a-decentralized-party.md)
* [Join the BitSafe Node Operator Network](/decentralization-manager/get-started/join-the-bitsafe-node-operator-network.md)
* [Architecture overview](/decentralization-manager/concepts-and-development/architecture-overview.md)
* [Backup, recovery, and upgrades](/decentralization-manager/operations-and-reference/backup-recovery-and-upgrades.md)

### Next step

👉 **Create the shared identity:** [Create a Decentralized Party](/decentralization-manager/get-started/create-a-decentralized-party.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bitsafe.finance/decentralization-manager/get-started/connect-peers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.