Installation

Requirements

Hardware

• Recommended 4 CPUs (minimum 2)

• Recommended 16GB Memory (minimum 8)

Translated to EigenLayer Node Classes, we recommend using a General Purpose XL node class

Software

• Docker

• Blockchain Web RPC Provider (i.e. Quicknode or your own custom endpoint)

Private Keys

• A private key representing your operator node

Network Ports

• Port 10000 is used for the inspection interface

• Port 20000 is used for P2P communication

• Port 30000 is used for the Management API

Depending on host provider and network setup, you may choose to remap external points to these internal ones.

For example, if your server's external IP is 1.2.3.4, you can choose to map port 80 on that external IP to port 10000 of your server's internal IP.

Quick Setup

Venn's node client software is called BlockBeat.

Written in GoLang, and released as a Docker image, BlockBeat provides unparalleled performance internally, while keeping Operator Experience in mind for easy setup and maintenance.

Simply copy and paste the following command in your terminal:

get-venn.sh

curl "https://storage.googleapis.com/venn-engineering/get-venn.sh" | bash -s my-venn-operator

This script will:

1. Create a new folder named my-venn-operator

2. Create a Makefile with helper commands to start, stop, update, and test your node

3. Create a config.yaml file in that folder with recommended defaults to get started

4. Create a protocols.yaml file in that folder, with whitelisted protocols your node will be allowed to inspect

5. Create a test-tx.json file in that folder, which is used for locally validating your node's basic setup

During Venn's testnet phase, only these whitelisted protocols will be inspected. See Testnet Guide for more info.

After running this script, you should see the following output:

Make sure to update config.yaml with your Private Key and Web3 Provider URLs

First Run

After adding your Private Key and Web3 Provider URLs to config.yaml, run the following command to start the node:

make venn-start

Running this command will start the BlockBeat docker image in foreground, streaming all logs to the terminal, as well as capturing the logs in the operator.log file. This mode is intended for testing purposes only. Running this mode in a production environment may result in operator.log growing beyond the system's available size, causing various issues. For production environments, make sure to run BlockBeat in the background.

Testing

Now that you have a node running, let's test it by sending it a test transaction to inspect. Run the following command in a new terminal window:

make venn-test

This will trigger a test transaction to your local node, and you should see output similar to the following:

{
  "requestId": "1dd1ada2-f515-46dd-9a2a-fb55200927f1",
  "approved": true,
  "signature": {
    "x": "0x14a975d4905b39ce015a7ac7694420ca12fa0899053b949fe4f8d209fb568f01",
    "y": "0x26da9f44b2767939945d07ad9af70b7964fb5e82e299e905a8d8952978e7f71c"
  },
  "metadata": [
    {
      "operator": "my-venn-operator/a80cab03a3e9",
      "approved": true,
      "signature": {
        "x": "0x14a975d4905b39ce015a7ac7694420ca12fa0899053b949fe4f8d209fb568f01",
        "y": "0x26da9f44b2767939945d07ad9af70b7964fb5e82e299e905a8d8952978e7f71c"
      }
    }
  ]
}

Success!

Our test transaction is approved by Venn, and our node setup verification is complete.

What's in the box?

config.yaml

A basic node operator configuration file.

config.yaml

venn:
  name: my-venn-operator

signer:
  signerPrivateKey: YOUR PRIVATE KEY HERE

detectors:
  detectionThreshold: 0.5
  detectors:
    - name: venn-testnet
      endpoint: http://detectors2.testnet.venn.build/services/detection/detect
      weight: 1

nodes:
  - chainId: 1
    nodes:
      - wsUrl: YOUR WEB-SOCKET PROVIDER URL HERE
        jsonUrl: YOUR HTTP PROVIDER URL HERE

protocolsFile: "/bb/protocols.yaml"

• name - can be anything you like, and will be used for identifying your node on the network, along with a unique-id that is auto-generated for you by BlockBeat

• signerPrivateKey - this is the key that represents your node on the Venn Network, which signs inspections results for transactions processed by your node

• nodes - the chains, blockchain nodes, and their respective Web3 Provider URLs. Multiple nodes can be configured per chain for redundancy, ensuring high-availability for your Venn node.

• detectors - these are the threat modeling mechanisms that the node uses to scan and analyze incoming transactions. During the current testnet phase, we recommend using Venn's external detector.

• protocolsFile - this is used during our current testnet phase to indicate which assets are protected by the node. Once Venn goes live on mainnet, this field will be deprecated in favor of an on-chain protocol-registration mechanism

See Configuration for more info

Makefile

Used as a helper file to start, stop, test, and update BlockBeat.

Using a Makefile is optional. Feel free to use any other method that is best suited for you and your team for running these shell commands

Makefile

# Just some configs for easier Docker wrangling
#
VERSION ?= latest
IMAGE_NAME = us-docker.pkg.dev/ironblocks/images/blockbeat:$(VERSION)
PORT_MAPPING = -p 10000:10000 -p 20000:20000 -p 30000:30000
CONTAINER_NAME = venn-operator
ENV_CONFIG_FILE = /bb/config.yaml
CONFIG_FILE_PATH = $(PWD)/config.yaml
PROTOCOLS_FILE_PATH = $(PWD)/protocols.yaml

# Default value for "background" is false
background ?= false

# Start the Venn node
#
# If "background" is set to true, the container will run in the background
# Otherwise,the container will run in the foreground and logs will be printed to stdout and captured into "operator.log"
venn-start:
	@if ! command -v docker > /dev/null; then \
		echo "Docker is not installed. Please install Docker first."; \
		exit 1; \
	fi
ifeq ($(background), true)
	docker run -d --rm \
		--name $(CONTAINER_NAME) \
		$(PORT_MAPPING) \
		-v $(CONFIG_FILE_PATH):/bb/config.yaml \
		-v ${PROTOCOLS_FILE_PATH}:/bb/protocols.yaml \
		-e CONFIG_FILE=$(ENV_CONFIG_FILE) \
		$(IMAGE_NAME)
else
	docker run -it --rm \
		--name $(CONTAINER_NAME) \
		$(PORT_MAPPING) \
		-v $(CONFIG_FILE_PATH):/bb/config.yaml \
		-v ${PROTOCOLS_FILE_PATH}:/bb/protocols.yaml \
		-e CONFIG_FILE=$(ENV_CONFIG_FILE) \
		-e ENV=dev \
		$(IMAGE_NAME) \
		| tee operator.log
endif

# Run a test transaction on the Venn node
#
venn-test:
	@if command -v jq > /dev/null; then \
		curl -X POST -H "Content-Type: application/json" -d @test-tx.json http://localhost:10000/signer | jq; \
	elif command -v python3 > /dev/null; then \
		curl -X POST -H "Content-Type: application/json" -d @test-tx.json http://localhost:10000/signer | python3 -m json.tool; \
	else \
		curl -X POST -H "Content-Type: application/json" -d @test-tx.json http://localhost:10000/signer; \
	fi

# Stop a running Venn node
#
venn-stop:
	docker stop $(CONTAINER_NAME)

# Update to the latest version of the Venn client software
#
venn-update:
	docker pull us-docker.pkg.dev/ironblocks/images/blockbeat:${VERSION}

test-tx.json

A simple test transaction you can use to make sure everything is up and running.

This transaction interacts with protocols that were whitelisted for Venn testnet phase. Once Venn goes live, and protocol whitelisting will be deprecated, you will be able to test your setup with any transaction data.

venn-test-tx.json

{
    "from": "0xfE6BB1654227fA21b8A65A6A89F6489fc3CC2fcD",
    "to": "0x47Ddb6A433B76117a98FBeAb5320D8b67D468e31",
    "data": "0xf2fde38b00000000000000000000000004b26cc3b326c22b4ed307c550296d102c23a06c",
    "value": "0x0",
    "gasPrice": "0x45574C259",
    "gas": "0xDA31",
    "blockNumber": "0x12CE79E",
    "chainId": 1
}

Running In Production

To run BlockBeat in production, run the following command:

make venn-start background=true

This runs the BlockBeat Docker image in the background, without streaming the output logs, and without writing logs to the operator.log file.

See Monitoring for more information