> ## Documentation Index
> Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# wattswarm node — Node Lifecycle and Network Commands

> Reference for all wattswarm node subcommands: bring nodes online, manage bootstrap contacts, sign network params, and update authority sets.

The `node` command group controls the lifecycle of a WattSwarm node: bringing it online, taking it offline, checking its status, and managing the network configuration it uses to connect to peers. You must call `node up` before submitting tasks or running executor flows.

***

## `node up`

Bring the node online and initialise the Iroh-backed P2P runtime.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] node up [--mode local|lan|wan]
```

**Flags**

| Flag     | Default | Description                                                                                                                                              |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--mode` | `local` | Network mode. `local` — single-machine, no P2P. `lan` — LAN peer discovery via mDNS. `wan` — WAN mode using configured bootstrap contacts and Iroh QUIC. |

**Description**

`node up` opens the node state directory, initialises the local PostgreSQL store, and starts the Iroh-backed network bridge when P2P is enabled. It writes a `node_state.json` file marking the node as running. The node identity is derived from `node_seed.hex` in the state directory — if the file does not exist, WattSwarm creates one automatically on first startup.

**Examples**

```bash theme={null}
# Start in local-only mode (no P2P)
wattswarm --state-dir ./.ws-dev node up

# Start in LAN mode
wattswarm --state-dir ./.ws-dev node up --mode lan

# Start in WAN mode (requires bootstrap contacts to be configured)
wattswarm --state-dir ./.ws-dev node up --mode wan
```

***

## `node down`

Take the node offline.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] node down
```

**Description**

`node down` updates `node_state.json` to mark the node as stopped. It does not delete any stored state, event log entries, or projections. You can bring the node back online with `node up` at any time.

**Example**

```bash theme={null}
wattswarm --state-dir ./.ws-dev node down
```

***

## `node status`

Show the current node status and peer protocol version distribution.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] node status
```

**Description**

Reads `node_state.json` and the local PostgreSQL store, then prints a JSON object with the node ID, running state, network mode, local protocol version, and a distribution map of connected peer protocol versions.

**Example**

```bash theme={null}
wattswarm --state-dir ./.ws-dev node status
```

```json theme={null}
{
  "running": true,
  "mode": "local",
  "local_protocol_version": "1",
  "peer_protocol_distribution": {}
}
```

***

## `node export-contact`

Print the Iroh contact string for this node so other nodes can bootstrap from it.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] node export-contact [--json]
```

**Flags**

| Flag     | Default | Description                                                                                                         |
| -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `--json` | false   | Output contact material as a JSON object instead of the short contact string. Intended for internal debugging only. |

**Description**

Prints the short `<iroh-node-id>@<host:port>` contact string for this node. Share this string with operators of joining nodes so they can add it as a bootstrap contact. The default text format is the canonical format accepted by `node add-bootstrap-contact`.

**Examples**

```bash theme={null}
# Export the short contact string (share with joining nodes)
wattswarm --state-dir ./.ws-genesis node export-contact
# Output: aef3b2...@203.0.113.10:4001

# Export as JSON (debugging only)
wattswarm --state-dir ./.ws-genesis node export-contact --json
```

***

## `node add-bootstrap-contact`

Add a bootstrap contact string to this node's startup configuration.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] node add-bootstrap-contact <contact> [--mode wan]
```

**Arguments**

| Argument    | Description                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------- |
| `<contact>` | The Iroh contact string exported by the genesis or bootstrap node (`<iroh-node-id>@<host:port>`). |

**Flags**

| Flag     | Default | Description                                                              |
| -------- | ------- | ------------------------------------------------------------------------ |
| `--mode` | `wan`   | Network mode to use when this contact is active. Must be `lan` or `wan`. |

**Description**

Appends the contact string to `startup_config.json` in the state directory. The node uses these contacts on next startup to establish its initial Iroh connection and trigger bootstrap sync of network params and org registry from the remote node.

<Note>
  Bootstrap contacts require `lan` or `wan` mode. Passing `--mode local` returns an error.
</Note>

**Example**

```bash theme={null}
wattswarm --state-dir ./.ws-joining node add-bootstrap-contact \
  'aef3b2...@203.0.113.10:4001' \
  --mode wan
```

***

## `node bootstrap-contacts`

List the bootstrap contacts configured in `startup_config.json`.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] node bootstrap-contacts
```

**Description**

Reads `startup_config.json` from the state directory and prints each configured bootstrap contact string, one per line.

**Example**

```bash theme={null}
wattswarm --state-dir ./.ws-joining node bootstrap-contacts
# Output:
# aef3b2...@203.0.113.10:4001
```

***

## `node sign-network-params`

Sign and store network protocol parameters (genesis node only).

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] node sign-network-params \
  --network-id <id> \
  [--params-file <path>] \
  [--pg-url <url>]
```

**Flags**

| Flag            | Description                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| `--network-id`  | The network identifier to sign params for (required).                                                    |
| `--params-file` | Path to a `NetworkProtocolParams` or signed envelope JSON file. Defaults to the built-in default params. |
| `--pg-url`      | Override the PostgreSQL connection string for this call.                                                 |

**Description**

Signs the network protocol parameters with the node's Ed25519 identity key and stores the signed envelope in the local PostgreSQL store. Use this on the genesis node to establish the authoritative network params that joining nodes will import during bootstrap sync.

**Example**

```bash theme={null}
wattswarm --state-dir ./.ws-genesis node sign-network-params \
  --network-id mainnet-alpha-1 \
  --params-file ./network-params.json
```

```json theme={null}
{
  "network_id": "mainnet-alpha-1",
  "version": 1,
  "prev_hash": null,
  "params_hash": "sha256:c1d2e3...",
  "signed_by": "node-pub-key-hex..."
}
```

***

## `node update-authority-set`

Update the authority set for a network.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] node update-authority-set \
  --network-id <id> \
  [--authority-set-file <path>] \
  [--pg-url <url>]
```

**Flags**

| Flag                   | Description                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--network-id`         | The network identifier (required).                                                                                                |
| `--authority-set-file` | Path to an `AuthoritySet` or signed envelope JSON file. Defaults to a genesis authority set derived from the local node identity. |
| `--pg-url`             | Override the PostgreSQL connection string for this call.                                                                          |

**Description**

Signs the authority set with the local node identity and stores it in the PostgreSQL store. Authority sets define which nodes hold signing authority on the network and are used for membership quorum validation and governance operations.

**Example**

```bash theme={null}
wattswarm --state-dir ./.ws-genesis node update-authority-set \
  --network-id mainnet-alpha-1 \
  --authority-set-file ./authority-set.json
```

```json theme={null}
{
  "network_id": "mainnet-alpha-1",
  "authority_set_id": 0,
  "prev_hash": null,
  "authority_set_hash": "sha256:9fa2b1...",
  "signed_by": "node-pub-key-hex..."
}
```