# ZMQ Notifications


> **2025 update:** ZeroMQ is no longer built into `blvm-node`. Use the **`blvm-zmq`** module. Configure endpoints in the module `config.toml` (same keys as former `[zmq]`). Repository: <https://github.com/BTCDecoded/blvm-zmq>.

BLLVM node supports ZeroMQ (ZMQ) notifications for real-time blockchain event notifications, compatible with standard Bitcoin node notification interfaces.

## Overview

ZMQ notifications allow external applications to receive real-time updates about blockchain events without polling. This is useful for:
- Block explorers
- Wallet applications
- Trading systems
- Monitoring tools
- Analytics platforms

## Supported Notification Types

BLLVM node supports all standard Bitcoin node ZMQ notification types:

### 1. `hashblock` - Block Hash Notifications

Publishes the 32-byte block hash when a new block is connected to the chain.

**Message Format:**
- Topic: `"hashblock"` (string)
- Data: Block hash (32 bytes)

**Example:**
```toml
[zmq]
hashblock = "tcp://127.0.0.1:28332"
```

### 2. `hashtx` - Transaction Hash Notifications

Publishes the 32-byte transaction hash when a transaction enters or leaves the mempool.

**Message Format:**
- Topic: `"hashtx"` (string)
- Data: Transaction hash (32 bytes)

**Example:**
```toml
[zmq]
hashtx = "tcp://127.0.0.1:28333"
```

### 3. `rawblock` - Raw Block Data Notifications

Publishes the complete serialized block data when a new block is connected.

**Message Format:**
- Topic: `"rawblock"` (string)
- Data: Serialized block (variable length)

**Example:**
```toml
[zmq]
rawblock = "tcp://127.0.0.1:28334"
```

### 4. `rawtx` - Raw Transaction Data Notifications

Publishes the complete serialized transaction data when a transaction enters or leaves the mempool.

**Message Format:**
- Topic: `"rawtx"` (string)
- Data: Serialized transaction (variable length)

**Example:**
```toml
[zmq]
rawtx = "tcp://127.0.0.1:28335"
```

#### Wire format for `rawblock` and `rawtx` payloads

Payloads use **Bitcoin P2P wire serialization** from `blvm-protocol` (`serialize_block` / `serialize_tx`): the same encoding as the `block` and `tx` P2P message bodies, **not** `bincode` or other ad hoc encodings.

**Migration:** Older builds published `rawblock`/`rawtx` using **bincode**. Subscribers and tools that assumed bincode bytes must be updated to decode P2P wire format (or re-serialize as needed). Treat this as a **breaking change** when upgrading from those builds.

### 5. `sequence` - Sequence Notifications

Publishes sequence notifications for mempool events with sequence numbers.

**Message Format:**
- Topic: `"sequence"` (string)
- Data: 33 bytes (1 byte type + 32 bytes transaction hash)
  - Type: `0x01` = mempool entry, `0x02` = mempool removal

**Example:**
```toml
[zmq]
sequence = "tcp://127.0.0.1:28336"
```

## Configuration

ZMQ notifications are configured in the node configuration file (TOML format):

```toml
[zmq]
# Block hash notifications
hashblock = "tcp://127.0.0.1:28332"

# Transaction hash notifications
hashtx = "tcp://127.0.0.1:28333"

# Raw block data notifications
rawblock = "tcp://127.0.0.1:28334"

# Raw transaction data notifications
rawtx = "tcp://127.0.0.1:28335"

# Sequence notifications
sequence = "tcp://127.0.0.1:28336"
```

All notification types are optional. Only configure the endpoints you need.

### Endpoint Format

ZMQ endpoints use the format: `transport://address:port`

**Supported Transports:**
- `tcp://` - TCP/IP (most common)
- `ipc://` - Inter-process communication (Unix domain sockets)
- `inproc://` - In-process communication (threads)

**Examples:**
- `tcp://127.0.0.1:28332` - Localhost TCP
- `tcp://0.0.0.0:28332` - All interfaces TCP
- `ipc:///tmp/bitcoin-hashblock` - Unix domain socket

## Enabling ZMQ Support

ZMQ support is **enabled by default** in BLLVM node, differentiating it from other Bitcoin implementations. This makes real-time notifications available out of the box.

To use ZMQ notifications:

1. **Configure endpoints** in your node configuration file (see above)

2. **Start the node** - ZMQ publisher will automatically initialize if configured

**Note:** Even though ZMQ is enabled by default, you can disable it in two ways:

1. **Don't configure endpoints** - If no ZMQ endpoints are configured, the ZMQ publisher won't initialize (no performance impact)

2. **Build without ZMQ feature** - To completely exclude ZMQ from the build:
   ```bash
   cargo build --no-default-features --features sysinfo,redb,nix,libc,utxo-commitments,production,governance
   ```

## Subscribing to Notifications

### Python Example

```python
import zmq

# Create ZMQ context and subscriber
context = zmq.Context()
subscriber = context.socket(zmq.SUB)

# Connect to hashblock endpoint
subscriber.connect("tcp://127.0.0.1:28332")

# Subscribe to hashblock topic
subscriber.setsockopt(zmq.SUBSCRIBE, b"hashblock")

# Receive notifications
while True:
    topic = subscriber.recv_string()
    block_hash = subscriber.recv()
    print(f"New block: {block_hash.hex()}")
```

### Rust Example

```rust
use zmq::{Context, SUB};

let ctx = Context::new();
let subscriber = ctx.socket(SUB)?;
subscriber.connect("tcp://127.0.0.1:28332")?;
subscriber.set_subscribe(b"hashblock")?;

loop {
    let topic = subscriber.recv_msg(0)?;
    let block_hash = subscriber.recv_msg(0)?;
    println!("New block: {:?}", block_hash);
}
```

### Node.js Example

```javascript
const zmq = require('zeromq');

// Create subscriber
const subscriber = zmq.socket('sub');

// Connect and subscribe
subscriber.connect('tcp://127.0.0.1:28332');
subscriber.subscribe('hashblock');

// Receive notifications
subscriber.on('message', (topic, blockHash) => {
    console.log('New block:', blockHash.toString('hex'));
});
```

## Integration with Event System

ZMQ notifications are automatically published when:
- **Blocks are connected**: `hashblock` and `rawblock` notifications are sent
- **Transactions enter mempool**: `hashtx`, `rawtx`, and `sequence` notifications are sent
- **Transactions leave mempool**: `sequence` notification is sent (with removal flag)

The ZMQ publisher is integrated with the node's event system, so notifications are published alongside module events.

## Performance Considerations

- **Zero-copy**: ZMQ uses efficient zero-copy message passing
- **Non-blocking**: ZMQ publishing is non-blocking and won't slow down block processing
- **Multiple subscribers**: Multiple applications can subscribe to the same endpoint
- **Fire-and-forget**: Failed ZMQ publishes are logged but don't affect node operation

## Security Considerations

- **Local access only**: By default, bind to `127.0.0.1` for local access only
- **Network access**: If binding to `0.0.0.0`, ensure proper firewall rules
- **No authentication**: ZMQ PUB/SUB sockets don't provide authentication
- **Use IPC**: For local applications, prefer `ipc://` over `tcp://` for better security

## Troubleshooting

### Notifications not received

1. **Check configuration**: Ensure ZMQ endpoints are configured correctly
2. **Check binding**: Ensure the endpoint address is correct
3. **Check subscription**: Verify subscriber is subscribed to the correct topic
4. **Check timing**: Allow time for ZMQ socket binding (100ms+)

**Note:** ZMQ is enabled by default in BLLVM node, so no special build flags are needed.

### Port conflicts

If you see "Address already in use" errors:
- Change the port number in configuration
- Check if another process is using the port
- Use `ipc://` endpoints instead of `tcp://` for local access

### Missing notifications

- Ensure node is processing blocks/transactions
- Check node logs for ZMQ errors
- Verify event publisher is initialized
- Check that ZMQ publisher was successfully created

## Compatibility

BLLVM node's ZMQ notifications are compatible with standard Bitcoin node ZMQ interfaces. Applications that work with standard Bitcoin ZMQ subscribers should work with BLLVM node without modification.

## Future Enhancements

Potential future improvements:
- Wire format serialization for rawblock/rawtx (currently uses bincode)
- Additional notification types
- Authentication support
- Compression options
- Rate limiting

## See Also

- [Event System Documentation](MODULE_SYSTEM.md)
- [Configuration Guide](CONFIGURATION_GUIDE.md)
- [ZeroMQ Documentation](https://zeromq.org/)

