# Introduction to Venn

## **What is Venn?**

Venn is a decentralized cybersecurity infrastructure that protects blockchain applications and protocols from malicious transactions and economic risks. It enables the proactive blocking of malicious activities and protects the operational continuity of blockchain applications by leveraging a combination of off-chain computation and on-chain execution capabilities. Venn's Actively Validated Service (AVS) leverages the crypto-economic security provided by EigenLayer.

<figure><img src="/files/M1X6YDiD9nlCFOCmv8Cp" alt=""><figcaption><p>Venn Security Network</p></figcaption></figure>

***

## **How Venn Works?**

Venn employs a unique architecture that integrates both on-chain and off-chain security mechanisms to deliver a distributed defense layer. The off-chain component involves a network of security operators who validate transactions before they are committed to the blockchain. These operators use numerous algorithms to examine each transaction and reach a consensus on its legitimacy. The on-chain component consists of smart contracts that enforce security policies in real-time during transaction execution, ensuring that any malicious activities are blocked without disrupting the protocol's functionality.&#x20;

### Decentralized Transaction Validation:

**Venn Security Network:** A decentralized network of node operators responsible for examining transactions and reaching a consensus on their legitimacy before committing to the blockchain. Each transaction undergoes thorough security checks to ensure it is not malicious. This competitive validation process ensures robust and diverse security assessments.

### On-chain Security Protection:

**Venn On-chain Firewall:** An open-source framework that enables developers to implement on-chain blocking mechanisms within their web3 applications. By integrating at the smart contract level, the firewall receives the network's consensus on the legitimacy of transactions and can block them accordingly.

***

## **Venn** Architecture

### Venn Root Network

The Venn Root Network is the foundational layer of the Venn ecosystem, ensuring security validation, consensus, and incentivization for all participants. It acts as the **primary** and **default** configuration.

Chains, protocols, developers, and operators who do not wish to create or join a dedicated subnet can join the Venn Root Network directly. This allows for participation without configuring or maintaining a custom subnet.

### Venn Subnets

In Venn, subnets are a powerful feature that provides a **flexible, customized, and dedicated security layer**. Operating on top of the main Venn root network, subnets allow chains, protocols, developers, security teams, and node operators to **build unique security-validating environments**. This enables the creation of **tailored security frameworks, threat detection models, and validation rules**.

Subnets offer security teams, node operators, and protocols to **establish customized subnetworks.** This enables network participants to **design and enforce security standards that align with specific operational goals**.

Additionally, subnets allow you to set **custom fees and payment** structures, enabling the establishment of on-chain agreements on fees, rewards, and service payments, all customized to fit your specific needs.

Two key models of operation are supported:

1\. **Dedicated Subnet for Chains and Protocols**: Protocols and chains can create their subnet to handle transaction validation and operational processes according to custom security requirements with a set of chosen node operators.&#x20;

2\. **Dedicated Security Models and Expertise**: Subnets can be configured to validate specific security domains, allowing operators to specialize in areas like threat prevention, governance, oracle manipulation, compliance, and user protection to create a dedicated subnet. This creates a decentralized, dedicated security environment where protocols can join subnets that align with their particular security needs.

<div data-full-width="true"><figure><img src="/files/wAaBybSXCtpFyD8MroyY" alt=""><figcaption></figcaption></figure></div>

***

## **Why Build with Venn?**

* **Proactive Security** - Venn's architecture is designed to proactively stop hacks and malicious activities rather than merely mitigating them after the fact.<br>
* **Decentralized and Reliable -** Leveraging a decentralized network of security operators ensures robust and reliable security assessments without relying on a single point of failure.<br>
* **Battle-Tested Security -** More than a concept, Venn is a proven technology that has prevented hacks worth over $2 million this year alone.<br>
* **Backtested -** Venn's testnet phase has rigorously tested its capabilities against most hacks from the past two years, ensuring it can stop attacks before they impact the blockchain state and demonstrating its effectiveness and accuracy.<br>
* **Cost-Effective Security -** Utilizing Venn's network eliminates the capital costs of securing blockchain applications, offering greater security at a much lower cost and effort.<br>
* **Leveraging Top Security Minds -** Venn utilizes top blockchain security experts and diverse methods, ensuring transactions are evaluated with powerful methods and diverse and distributed algorithms. This allows developers to access multiple security methods rather than relying on a single vendor.<br>
* **Incentivized**: Venn’s architecture ensures active and meaningful participation across the network. Node operators, security teams, protocols, and developers are rewarded based on their contributions to the ecosystem's security, performance, and growth.&#x20;


# Getting Started

This section is your gateway to understanding and engaging with the Venn ecosystem, tailored to your specific role. Whether you are a Node Operator, a member of a Security Team, or a Developer, you will find all the necessary information, tools, and guidance to begin your journey with Venn.

***

## **Protocols & Developers**

Leverage Venn’s infrastructure to securely build and scale your applications. Learn how to connect your projects, dApps, and ecosystem to the Venn infrastructure, providing unparalleled security and reliability.&#x20;

## **Node Operators**

Validate transactions and maintain the network's infrastructure while earning incentives. As a node operator, you will learn to set up and manage your node, stake tokens, and participate in transaction validation.

## **Security Teams**

Design and implement cutting-edge security measures on Venn and get rewarded. You will learn about the processes for integrating your security tools and methods with the Venn network and the rewards for identifying and resolving security issues.

***

## Next Steps

Choose your role below to access 'Getting Started' guides and resources:

<table data-view="cards"><thead><tr><th data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="/files/UPJp6GprP2fMf8B4NvdR">/files/UPJp6GprP2fMf8B4NvdR</a></td><td><a href="/pages/l2IrO9NWXTfYj2rLbRVf">/pages/l2IrO9NWXTfYj2rLbRVf</a></td></tr><tr><td><a href="/files/Bq8JOucOXjzvnTU5iLuY">/files/Bq8JOucOXjzvnTU5iLuY</a></td><td><a href="/pages/8zPBoYCdqXDGztxbp7ux">/pages/8zPBoYCdqXDGztxbp7ux</a></td></tr><tr><td><a href="/files/aF2fHbOQcbnq9Fr2k9M2">/files/aF2fHbOQcbnq9Fr2k9M2</a></td><td><a href="/pages/gqHISUPohEmUyTRAq4Uw">/pages/gqHISUPohEmUyTRAq4Uw</a></td></tr></tbody></table>


# Protocols & Developers

This page is designed to provide Protocols and developers with the essential tools, resources, and guidance needed to leverage Venn’s infrastructure to build and scale your projects securely.

***

{% hint style="info" %}
Venn is currently active on the **Super-Layer Incentivized Testnet**. To participate and contribute to the network at this stage, you can [**join the testnet waitlist**](https://www.venn.build/).
{% endhint %}

## Introduction

By integrating your smart contracts, apps, applications, or rollup with Venn, developers can enhance their applications with advanced security features, ensuring their projects are protected against a wide range of threats. Venn's decentralized infrastructure allows developers to focus on innovation while the Venn network handles security and performance.

## **Make Sure You Have the Help You Need!**

We’re here to support you every step of the way. If you have questions, need guidance, or want to connect with other developers and protocols, be sure to check out our support channels:

* **Discord:** Join our [developer community](https://discord.com/invite/venn) on Discord for real-time support, discussions, and updates.
* **Telegram:** Connect with other developers and get quick answers to your questions in [our Telegram](https://t.me/vennbuilders).

***

## **Why Venn?**

In the fast-paced world of blockchain development, developers face challenges such as tight budgets, time constraints, market conditions, and the need for robust, custom, straightforward, and proactive security for your assets and users' funds. Venn addresses these issues by providing:

1. **Unified Security:** Access diverse and comprehensive security solutions, integrating multiple top-tier security providers and methods to offer a cohesive and robust defense mechanism.
2. **Decentralized Trust:** Leverage a decentralized network that ensures secure transaction validation while reaching a consensus and eliminating single points of failure.
3. **Cost Efficiency:** Benefit from optimized cost structures in which your end-users pay security gas fees that are a fraction of the transaction gas fee, while developers can also subsidize these costs for their ecosystem.
4. **Incentivized Participation:** Developers are rewarded for joining, participating, and supporting the Venn network, encouraging active engagement and innovation within the ecosystem.
5. **Community**: Access to a vibrant community of developers, security experts, and node operators, offering shared knowledge, resources, and continuous support to help you succeed.

***

## **What You'll Find Here**

1. **Integration Guides:** Step-by-step tutorials on integrating your dApps with Venn’s infrastructure. Learn how to connect your projects to the network, configure security settings, and deploy it seamlessly.
2. **On-Chain Firewall:** Documentation on Venn’s on-chain firewall, including instructions on how to set it up and manage it.
3. **dApp Frontend SDK:** Detailed guides on connecting your application frontend SDK with Venn.

***


# Installation

Welcome to the Venn Network installation guide for protocols and developers. This guide details the steps needed to secure your protocols with Venn.

***

## Overview

### To protect your protocols with Venn you will need to:

1. Integrate the **Firewall SDK** into your smart contracts.&#x20;
2. **Register** your smart contracts on-chain with Venn.
3. Install the **dApp SDK** on your frontend.

{% hint style="info" %}
Before you start the installation, take some time to familiarize yourself with the Venn stack using the tools designed specifically for developers:\
\
[**Venn Playground:**](https://explorer.venn.build/playground)\
A demo dApp that enables you to try Venn integrations, helping you understand how Venn works. <br>

[**Hello Venn:**<br>](https://github.com/ironblocks/hello-venn)A “Hello World” repository designed to gain hands-on experience with the integration process and explore Venn's capabilities in a local controlled environment.
{% endhint %}

***

## Step 1 - Integrate the **Firewall SDK**

### Install the Venn CLI

Start by installing the Venn CLI. This will allow you to add the Firewall SDK to your smart contracts and register them on the chain.

```sh
npm i -g @vennbuild/cli
```

*This command installs the CLI globally, making the* <kbd>**venn**</kbd> *command available in your terminal.*

### Integrate the Firewall SDK

The Firewall SDK adds the[ security modifiers](/venn-network/getting-started/protocols-and-developers/how-it-works) to your smart contracts. Run this command from the root folder of your project to integrate the SDK:

```sh
venn fw integ -d contracts
```

*This command scans all smart contracts in the* <kbd>**contracts**</kbd> *folder and automatically adds the required import* <kbd>**VennFirewallConsumer**</kbd> *to the external functions.*

#### Example:

Before Integration:

```solidity
pragma solidity ^0.8;

contract MyContract {
    
    myMethod() {
        ...
    }
}
```

After Integration:

```solidity
pragma solidity ^0.8;

import {VennFirewallConsumer} from "@ironblocks/firewall-consumer/contracts/consumers/VennFirewallConsumer.sol";

contract MyContract is VennFirewallConsumer {

    myMethod() firewallProtected {
        ...
    }
}
```

{% hint style="success" %}
Now that your smart contracts include the Firewall SDK, deploy them as you normally would on any network - this will enable you to register them on-chain to Venn, in the next step.
{% endhint %}

***

## Step 2 - **Register** your smart contracts with Venn.

{% hint style="info" %}
This step connects your Firewall-protected smart contracts to the Venn Network on-chain by sending setup transactions.
{% endhint %}

### **Before You Begin**

* Complete step 1: Firewall SDK integration on your smart contracts.&#x20;
* Ensure your smart contracts are deployed on-chain.
* Have your deployment private key ready (this must be the same key used for deployment).

### **Configuration**

1. Create a configuration file named **`venn.config.json`** in your project’s root directory.
2. Update the file with your deployed contract addresses. Example:

```json
{
    "networks": {
        "holesky": {
            "contracts": {
                "MyContract1": "0x1234abcd1234abcd1234abcd1234abcd1234abcd",
                "MyContract2": "0x1234abcd1234abcd1234abcd1234abcd1234abcd",
            }
        }
    }
}
```

* Each key in the `contracts` object is the **Name** of the contract
* Each value in the `contracts` object is the **Address** of the contract

3. Create an environment variable called <kbd>**VENN\_PRIVATE\_KEY**</kbd> with the private key that deployed your smart contracts.

{% hint style="warning" %}
**IMPORTANT:** This key **must** be the same key that deployed the smart contracts
{% endhint %}

### **Connect To Venn**

Run this command to register your Firewall-protected smart contracts with Venn:

```bash
venn enable --network holesky
```

### **Your Venn Policy**

After a successful connection to Venn, a new Venn Security Policy is created for you. The policy address is automatically saved in your <kbd>**venn.config.json**</kbd> file, for example:

```json
{
    "networks": {
        "holesky": {
            "contracts": {
                "MyContract1": "0x1234abcd1234abcd1234abcd1234abcd1234abcd",
                "MyContract2": "0x1234abcd1234abcd1234abcd1234abcd1234abcd",
            },

            // YOUR VENN POLICY ADDRESS
            "policyAddress": "0x123..."
        }
    }
}
```

{% hint style="info" %}
You will use the<kbd>**policyAddress**</kbd> in the next step, when setting up your dApp frontend.
{% endhint %}

***

## Step 3 - Set Up the **dApp SDK** on your frontend.

Now that your smart contracts are secured, only approved transactions will be executed on-chain. To also approve transactions that go through your dApp frontend, you will need to install Venn-SDK in your dApp.&#x20;

### **Install the SDK**

In your dApp frontend project, open a new terminal and install the SDK.

```bash
npm i @vennbuild/venn-dapp-sdk
```

### Initialize **a New** VennClient **Instance**

Import the VennClient and create a new instance by providing the Venn node URL and your Venn policy address from step 2:

```javascript
import { VennClient } from '@vennbuild/venn-dapp-sdk';

const vennURL           = process.env.VENN_NODE_URL;          // URL of your Venn node operator
const vennPolicyAddress = process.env.VENN_POLICY_ADDRESS;      // Your Venn policy address

const vennClient = new VennClient({ vennURL, vennPolicyAddress });

```

* <kbd>**vennURL**</kbd>, a URL pointing to a Venn node operator:

{% code title="Venn node operator:" %}

```
https://signer2.testnet.venn.build/api/17000/sign
```

{% endcode %}

* <kbd>**vennPolicyAddress**</kbd>: the <kbd>**policyAddress**</kbd> You got from "Register With Venn" in step 2.

### Approving Transactions

Use the SDK to validate transactions before sending them on-chain:

```typescript
const approvedTransaction = await vennClient.approve({
    from,
    to,
    data,
    value
});

// You can now send the approvedTransaction as you normally would
const receipt = await wallet.sendTransaction(approvedTransaction);
```

{% hint style="success" %}
That's it! Welcome to Venn. :tada:  You can now view your activity on Venn in the [Explorer](https://explorer.venn.build/transactions).
{% endhint %}

***

## Reference Documentation

* [Venn CLI](https://www.npmjs.com/package/@vennbuild/cli)
* [Venn DApp SDK](https://www.npmjs.com/package/@vennbuild/venn-dapp-sdk)


# Testnet Guide

## Introduction

Integrating with the Venn testnet allows you to safely validate your integration and setup while experiencing the functionality of Venn’s security infrastructure in a controlled environment.

By joining the testnet, you can explore how Venn actively protects your smart contracts from threats, fine-tune your security, and optimize performance — without the concerns of deploying on the mainnet or disrupting your operations.

This guide will walk you through the steps to test Venn’s capabilities, helping you build confidence in your configurations before going live in Mainnet.

{% hint style="info" %}
We're on Holesky! *(additional testnets coming soon)*
{% endhint %}

{% hint style="info" %}
**Tip:** Getting a Holesky Faucet. To interact with the Venn testnet, you'll need Holesky testnet tokens. You can easily get them from one of the following Holesky faucets:

* [Google](https://cloud.google.com/application/web3/faucet/ethereum/holesky)
* [QuickNode](https://faucet.quicknode.com/ethereum/holesky)
  {% endhint %}

***

## Mock Rejection

When testing the integration between Venn and your protocol, you will want to make sure that the integration works as expected both for approved **as well as unapproved transactions**.

To facilitate this, we've created a dedicated endpoint that will **always reject** incoming transactions, allowing you to test how your application handles such scenarios. This endpoint can then be used in the **DApp SDK.**

{% hint style="info" %}
For the best developer experience, we recommend using environment variables for the **`vennURL`** parameter
{% endhint %}

```typescript
// Reading vennURL from the VENN_NODE_URL env variable
// allows your to easily switch between the real endpoint
// and the mock-rejection endpoint, without making changes
// to your DApp's code
//
const vennURL = process.env.VENN_NODE_URL;
const vennClient = new VennClient({ vennURL, ... });
```

***

## Testnet Resources

### Holesky

<table><thead><tr><th width="220">When Using</th><th width="536">Pass In</th></tr></thead><tbody><tr><td><strong>Venn CLI</strong></td><td><code>--network holesky</code></td></tr><tr><td><strong>Venn DApp SDK</strong></td><td><code>vennURL: "https://signer2.testnet.venn.build/api/17000/sign"</code></td></tr><tr><td><strong>Mock Rejection URL</strong></td><td><code>vennURL: "https://signer2.testnet.venn.build/api/17000/mock/reject"</code></td></tr></tbody></table>

***

## Support

We deeply appreciate your support and commitment to our vision of a secure Web3.\
For any assistance during the integration process or after, our technical support team is ready to help.

* **Join Venn Discord - T**o access support, join the Venn Discord community using the link below:\
  [Venn Discord - Join Here](https://discord.gg/97cg6Qhg)<br>
* **Open a Support Ticket -** Once in the Discord server, navigate to the `#support-ticket` channel and open a ticket. Our team will respond promptly to assist you


# EthGlobal Bangkok

## What is Venn

Venn stops exploit transactions before they even hit the blockchain, securing every transaction in real-time through a decentralized and modular network of security operators.

Hi and welcome to the Venn Challenge for DC7SEA 👋

* Learn more at: [Venn Site](https://www.venn.build/) | [Venn Playground](https://playground.venn.build/)

### Venn Prize - $1,000

### Instructions

In this challenge, you'll deploy a new Venn Firewall and integrate it into your smart contracts to enhance your project's security.

Once completed, you'll also need to integrate Venn DApp SDK to your DApp's Frontend so that transactions get approved before being sent onchain.

Ready ? Let's go 💪

### Step 1: Clone Venn challenge repo

1. Clone the repo and install dependencies:

```
git clone https://github.com/ironblocks/DC7-SEA
cd DC7-SEA
npm ci
```

2. Setup your private key and hardhat network configuration

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

```
PRIVATE_KEY=...
RPC_URL=...
```

3. Compile

```
npm run firewall:compile  # the warning are a feature, not a bug 😅
```

4. Deploy a new Firewall

Venn Firewall is an onchain solution that can surgically prevent malicious transactions from going through, only allowing approved transactions to be executed.

```
npm run firewall:deploy -- --network <network>
```

5. Note the new `venn.config.json` file that was created with the Firewall address in it. We'll use this later in **Step 4**.

### Step 2: In Your Smart Contracts Repo

Now that the Firewall is deployed, you'll use various Venn SDKs to integrate Venn with your project.

1. Install the CLI:

```
npm i -g @vennbuild/cli
```

2. Run the CLI to add the Firewall to your smart contracts:

```
venn fw integ -r -d contracts
```

**Before**

```solidity
pragma solidity ^0.8;

contract MyContract {
    
    myMethod() {
        ...
    }
}
```

**After**

```solidity
pragma solidity ^0.8;

import {VennFirewallConsumer} from "@ironblocks/firewall-consumer/contracts/consumers/VennFirewallConsumer.sol";

contract MyContract is VennFirewallConsumer {

    myMethod() firewallProtected {
        ...
    }
}
```

Now that your smart contracts include the Firewall SDK, deploy them as you normally would onto any network.

3. Deploy your contracts as you normally would:

```
hardhat run scripts/deploy.js   # your deployment script
```

## Step 3: Back In The Challenge Repo

Now that your smart contracts have integration with Venn, you'll need to send a setup transaction to enable the Firewall.

1. Remember `venn.config.json` ? time to use it. Open this file and add your contracts addresses:

```json
{
    "networks": {
        "holesky": {
            "firewall": "0x123...",

            "contracts": {
                "MyContract1": "0x11111...",
                "MyContract2": "0x22222..."
            }
        }
    }
}
```

2. Run the setup script. This script will send setup transactions from the `PRIVATE_KEY` you've configured in the `.env` file to turn on the Firewall on each of your contracts:

```
npm run firewall:setup -- --network <network>
```

## Step 4: Your Repo Again (last time i promise!)

With the Venn Firewall enabled on your smart contracts, transactions need to be approved via Venn Network before they can be submitted on chain.

To do this, you'll add our Venn DApp SDK to your DApp's Frontend.

1. Install the SDK

```
npm i @vennbuild/venn-dapp-sdk
```

2. Create a new instance of the SDK Client

```javascript
import { VennClient } from '@vennbuild/venn-dapp-sdk';

const vennURL           = "https://dc7sea.venn.build/sign";
const vennPolicyAddress = YOUR FIREWALL ADDRESS;

const vennClient = new VennClient({ vennURL, vennPolicyAddress });
```

3. Update your DApp to approve transactions before submitting them onchain:

```javascript
// You probably have something like this:
const tx = { to, from, data, value };
const receipt = await wallet.sendTransaction(approvedTransaction);


// But now you need this:
const tx = { to, from, data, value };
const approvedTransaction = await vennClient.approve(tx);
const receipt = await wallet.sendTransaction(approvedTransaction);
```

### Kinto Prize - $500

See here \[[link](https://docs.kinto.xyz/kinto-the-safe-l2/building-on-kinto/tools/firewall-venn)] for projects building on Kinto to learn more.

<br>


# Governance

## Setting The Firewall Address <a href="#setting-the-firewall-address" id="setting-the-firewall-address"></a>

Once a [Firewall Consumer](https://docs.ironblocks.com/firewall/glossary#firewall-consumer) is deployed, you need to tell it what Firewall to use - i.e. give it the address of a Firewall so that it can start consuming its security services. Initially, every [Firewall Consumer](https://docs.ironblocks.com/firewall/glossary#firewall-consumer) has it's `_firewall` data set to the zero address `0x0`.

1. To set the Firewall address, call the [setFirewall()](https://docs.ironblocks.com/firewall/smart-contracts/firewallconsumer.sol#setfirewall) method

## Changing The Firewall Admin <a href="#changing-the-firewall-admin" id="changing-the-firewall-admin"></a>

The [Firewall Admin](https://docs.ironblocks.com/firewall/glossary#firewall-admin) is the principal *(person, people, or organization)* that is allowed to perform administrative tasks on your [Firewall Consumer](https://docs.ironblocks.com/firewall/glossary#firewall-consumer).

1. To set the Firewall Admin, call the [setFirewallAdmin()](https://docs.ironblocks.com/firewall/smart-contracts/firewallconsumer.sol#setfirewalladmin) method


# How It Works

## Overview

When you add protection to your smart contracts via the Firewall SDK, your smart contracts become **`VennFirewallConsumers`** *(i.e. they now consume security services from the Firewall)*.

This allows you to make use of the **`firewallProtected`** modifier on any external function that is exposed by your smart contracts:

```solidity
pragma solidity ^0.8;

import {VennFirewallConsumer} from "@ironblocks/firewall-consumer/contracts/consumers/VennFirewallConsumer.sol";

contract MyContract is VennFirewallConsumer {

    myMethod() external firewallProtected {
        ...
    }
}
```

## `firewallProtected` Modifier

Behind the scenes, this modifier will forward every call to the protected function to the Firewall, which makes sure that the call has been approved by Venn before allowing it to go through.

Once the approval is confirmed by the Firewall, normal execution continues as normal.


# Roles

An overview of the Venn Firewall roles

## Firewall Admin

The `FIREWALL_ADMIN` is the wallet or account that can configure your firewall's settings. Such as which `Firewall` instance your smart contracts use, what security policies are enabled, and whether the policies are enabled globally or on specific methods.

### Default Configuration

By default, when you [integrate the Firewall SDK](https://docs.venn.build/venn-network/getting-started/protocols-and-developers/installation#step-1-integrate-the-firewall-sdk) into your smart contracts `FIREWALL_ADMIN` role is set as `msg.sender`- which means it's the same as the wallet or account that was used to deploy your smart contracts.

### Changing The Default Configuration

After your smart contracts have been deployed, the `FIREWALL_ADMIN` can call the `setFirewallAdmin(...)`followed by a call to `acceptFirewallAdmin()`to set a new Firewall Admin on your smart contract:

```
setFirewallAdmin(address _newFirewallAdmin)
```

```
acceptFirewallAdmin()
```

{% hint style="warning" %}
The Firewall Admin must be set per each smart contract using the Venn Firewall
{% endhint %}


# Node Operators

{% hint style="warning" %}
Venn is currently operating in a permissioned mode. If you are interested in joining Venn as a node operator, please contact us to express your interest and learn more about the requirements and process.
{% endhint %}

## **What is a Node Operator within Venn?**

Node operators run the core Venn infrastructure to validate transactions and ensure the network's overall functionality. The Venn node architecture is designed to run on your existing nodes or be deployed as a dedicated node, making it highly modular, cost-efficient, and easy to maintain. In the Venn ecosystem, there are two types of operators:

1. **Infrastructure Node Operators**: These operators focus on the technical infrastructure, ensuring the network runs smoothly and efficiently. Infrastructure operators can run the default threat model provided by Venn or choose any other threat model from any security team based on past performance and personal preferences. [Start Installation ](/venn-network/getting-started/node-operators/installation)
2. **Security Node Operators**: These operators specialize in security validation, developing custom transaction analyses for potential threats and malicious activities. Security teams can integrate their unique threat models into the Venn node client using an SDK, allowing you to enforce specific security policies tailored to their expertise and approach. [Start Building Custom Threat Models](/venn-network/getting-started/security-teams)


# Installation

## **Requirements** <a href="#software-requirements" id="software-requirements"></a>

### Hardware

* Recommended 4 CPUs *(minimum 2)*
* Recommended 16GB Memory *(minimum 8)*

{% hint style="info" %}
Translated to [EigenLayer Node Classes](https://docs.eigenlayer.xyz/eigenlayer/operator-guides/eigenlayer-node-classes), we recommend using a **General Purpose XL** node class
{% endhint %}

### 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

{% hint style="info" %}
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.
{% endhint %}

## 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.<br>

Simply copy and paste the following command in your terminal:

{% code title="get-venn.sh" overflow="wrap" fullWidth="false" %}

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

{% endcode %}

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

{% hint style="warning" %}
During Venn's testnet phase, only these whitelisted protocols will be inspected.\
\
See [Testnet Guide](/venn-network/getting-started/node-operators/testnet-guide) for more info.
{% endhint %}

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

<figure><img src="/files/rlyFDYPMbiwf1KaULFOe" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Make sure to update `config.yaml` with your `Private Key` and `Web3 Provider` URLs&#x20;
{% endhint %}

### First Run

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

```sh
make venn-start
```

{% hint style="warning" %}
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**.
{% endhint %}

### 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:

```sh
make venn-test
```

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

{% code overflow="wrap" lineNumbers="true" %}

```json
{
  "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"
      }
    }
  ]
}
```

{% endcode %}

{% hint style="success" %}
Success!

Our test transaction is approved by Venn, and our node setup verification is complete.
{% endhint %}

## What's in the box?

### config.yaml

A basic node operator configuration file.

{% code title="config.yaml" lineNumbers="true" %}

```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"

```

{% endcode %}

* `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<br>
* `signerPrivateKey` - this is the key that represents your node on the Venn Network, which signs inspections results for transactions processed by your node<br>
* `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.<br>
* `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.<br>
* `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

{% hint style="info" %}
See [Configuration](/venn-network/getting-started/node-operators/configuration) for more info
{% endhint %}

### Makefile

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

{% hint style="info" %}
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
{% endhint %}

{% code title="Makefile" lineNumbers="true" %}

```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}

```

{% endcode %}

### test-tx.json

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

{% hint style="info" %}
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.
{% endhint %}

{% code title="venn-test-tx.json" lineNumbers="true" %}

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

{% endcode %}

## Running In Production

To run BlockBeat in production, run the following command:

```sh
make venn-start background=true
```

{% hint style="info" %}
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](/venn-network/getting-started/node-operators/monitoring) for more information
{% endhint %}


# Registration


# Configuration

## Overview

You can configure various aspects of how your node operates, focusing on these topics:

* **Node Management**\
  Configure what address, port, and route the node uses for the Node Management API.\
  Alternatively, you can use opt to disable this API altogether.

* **Security Inspection Signature**\
  Configure what address, port, route, and private key the node uses when inspecting and signing transactions.

* **Threat Modeling Detectors**\
  Venn's threat modeling works by leveraging Detectors.\
  Use this configuration section to what detectors your node uses when inspecting incoming transactions.

* **Blockchain Nodes**\
  Your node can interact and protect transactions for any EVM-like blockchain.\
  Use this configuration section to setup the Web3 providers and chains your node interacts with.

* **Protocol Registration**\
  This configuration section tells the node what protocols are whitelisted for Venn's protection through your node. Only whitelisted protocols can use your node for transaction inspection.

* **Network & Peer Management**\
  Use this section to configure your operator's display name on the network, as well as what hostname, port, and route it exposes for peer-to-peer communication on the Network.\
  This is also where you configure what peers your node is connected to.

{% hint style="warning" %}
**During Venn Testnet phases, protocol registration and peer discovery is handled manually, in a permissioned model**.

\
Once Venn goes live no mainnet, both protocol registration and peer discovery will be done on-chain through dedicated registration contracts.
{% endhint %}

## Node Management

```yaml
# Node Management - The configuration for the Operator's Management API
# Mandatory: no
management:
  
  # disabled - Whether the Operator Management API is disabled
  # Default: false
  # Mandatory: no
  disabled: false
  
  # host - The host of the Operator Management API
  # Default: 0.0.0.0 - listen on all interfaces
  # Mandatory: no
  host: 0.0.0.0
  
  # port - The port of the Operator Management API
  # Default: 30000
  # Mandatory: no
  port: 30000
  
  # path - The path of the Operator Management API
  # Default: none
  # Mandatory: no
  path:
  
```

## **Security Inspection Signature**

```yaml
# Security Inspection Signature - The configuration for the Operator Signer
# Mandatory: yes
signer:

  # host - The host of the Operator Signer API
  # Default: 0.0.0.0 - listen on all interfaces
  # Mandatory: no
  host: 0.0.0.0
  
  # port - The port of the Operator Signer API
  # Default: 10000
  # Mandatory: no
  port: 10000
  
  # path - The path of the Operator Signer API
  # Default: /signer
  # Mandatory: no
  path: /signer
  
  # signerPrivateKey - The private key of the external signer
  # Default: none
  # Mandatory: yes
  signerPrivateKey: "PRIVATE_KEY"

```

## **Threat Modeling Detectors**

<pre class="language-yaml"><code class="lang-yaml"><strong># Threat Modeling Detectors - The configuration for the Operator external Detectors configuration
</strong># Default: none
# Mandatory: yes
detectors:

  # detectionThreshold - minimum threshold for detection
  # Default: 0
  # Mandatory: yes
  detectionThreshold: 0.5

  # detectors - The detectors to use for the signer
  # Mandatory: yes
  detectors:
  
      # name - The name of the detector
      # Default: none
      # Mandatory: yes
    - name: processor
    
      # endpoint - The endpoint of the detector
      # Default: none
      # Mandatory: yes
      endpoint: http://detectors.testnet.venn.build:40000/api/external-detector
    
      # weight - The weight of the detector when calculating the detection score must be greater than 0
      # Default: none
      # Mandatory: yes
      weight: 0.9

      # timeoutSeconds - The timeout in seconds for the detector
      # Default: 30 seconds
      # Mandatory: no
      timeoutSeconds: 30

</code></pre>

## **Blockchain Nodes**

```yaml
# Blockchain Nodes - The nodes to connect to for the signer retrieval of transaction simulation
# Default: none
# Mandatory: yes
nodes:
  
  # chainId - The chainId of the network
  # Default: none
  # Mandatory: yes
  - chainId: 1
    
    # nodes - A List of nodes to connect to for the particular chainId. at least one node is required for each chainId
    # Default: none
    # Mandatory: yes
    nodes:
        
        # wsUrl - The websocket url of the node
        # Default: none
        # Mandatory: yes
      - wsUrl: "WSS_URL"
        
        # jsonUrl - The json rpc url of the node
        # Default: none
        # Mandatory: yes
        jsonUrl: "JSON_URL"
        
        # type: The type of the node
        # Default: ethereum
        # Mandatory: no
        type: ethereum

```

## **Network & Peer Management**

```yaml
# Network & Peer Management - The configuration for the Venn Operator and its peers
# Default: none
# Mandatory: yes
venn:
  
  # name - The name of the Operator - can be any string
  # Default: hostname
  # Mandatory: no
  name: operator-1
    
  # operatorId - The id of the Operator (the name that broadcast to other peers) - can be any string
  # Default: hostname
  # Mandatory: no
  operatorId: "operator-1"
  
  # host - The host of the Operator Blockbeat listening on
  # Default: 0.0.0.0 - listen on all interfaces
  # Mandatory: no
  host: 0.0.0.0
  
  # port - The port of the Operator Blockbeat listening on
  # Default: 20000
  # Mandatory: no
  port: 20000
  
  # peers - The peers of the Operator
  # Default: none
  # Mandatory: no
  peers:
      # name - The name of the peer
      # Default: none
      # Mandatory: yes
    - name: eu-testnet-venn-build
  
      # endpoint - The endpoint of the peer
      # Default: none
      # Mandatory: yes
      endpoint: http://europe.testnet.venn.build:20000
  
      # timeoutSeconds - The timeout in seconds for the peer to respond
      # Default: 60 seconds
      # Mandatory: no
      timeoutSeconds: 60

      # checkIntervalSeconds - The interval in seconds to check the peer health
      # Default: 60 seconds
      # Mandatory: no
      checkIntervalSeconds: 60

```

## **Protocol Registration**

```yaml
# Protocol Registration - The protocols the Operator is protecting
# Default: none
# Mandatory: yes
protocols:
  # chainId - The chainId of the network that the protocol is on
  # Default: none
  # Mandatory: yes
  - chainId: 1
    
    # protocols - A List of protocols to protect on the particular chainId. at least one protocol is required for each chainId
    protocols:
      
      # name - The name of the protocol
      # Default: none
      # Mandatory: yes
      - name: Protocol1
        
        # addresses - A list of addresses related to the protocol
        # Default: none
        # Mandatory: yes
        addresses:
          - "0x<some_address_1>"
          - "0x<some_address_2>"

```


# Monitoring


# Testnet Guide

## Introduction

This guide provides information on what you can expect during this testnet phase.\
Our key objectives for this permissioned testnet are.

## Objectives

During Venn's testnet phase we will work to reach the following KPIs:

1. [False Negative](#user-content-fn-1)[^1] Ratio of **10% or less**
2. [False Positive](#user-content-fn-2)[^2] Ratio of **1% or less**
3. Response Time of **500ms or less**

## What To Expect?

As we go through the testnet phases, we will be onboarding select node operators onto Venn. Once your node is up and running *(see* [*Installation*](/venn-network/getting-started/node-operators/installation)*)* it will actively participate in each of these phases, strengthening Venn's security and performance.

* For phase one, Venn will replay 70 hacking transactions for inspection twice a day
* For phase two, Venn will replay [all transactions for hacked protocols](#user-content-fn-3)[^3] from January 1st 2023 to the present day
* After setup, our engineering team may get in touch with software updates as needed

## Testnet Phases

Fine tuning Venn to reach these APIs will be completed in systematic phases.

### 1. False Negatives

{% hint style="info" %}
Phase 1 is currently in progress
{% endhint %}

* **Goal**\
  Minimize false negatives<br>
* **Test Set**\
  Transactions from at least 70 hacked protocols on mainnet Ethereum, from January 1, 2023 to the present<br>
* **Procedure**\
  Simulate all 70 transactions on all operators twice daily<br>
* **Rationale**\
  During this first phase, we'll make sure Venn can collectively identify hacked transactions, ignoring any other noise in the data<br>

### 2. False Positives

* **Goal**\
  Minimize false positives<br>
* **Test Set**

  All transactions from the same 70 protocols, starting from January 1st 2023 to present day<br>
* **Procedure**

  Cycle simulations based on overall network performance<br>
* **Rationale**\
  Now that Venn surgically detects the hacked transactions, we want to make sure it truthfully signs off on any and all other interactions for the same protocols in the test data

### 3. Performance

* **Goal**\
  Onboard operators at scale<br>
* **Test Set**\
  Up to 20 operators for this permissioned-phase testnet<br>
* **Procedure**\
  We will gradually onboard more nodes as we progress through the test phases, supporting operators and iterating on performance improvements<br>
* **Rationale**\
  This allows us to responsibly onboard node operators onto Venn, while still cycling through our test phases with fast iterations

## Test Data

We chose 70 hacked protocols for their diversity in industry, total value locked (TVL), attack vectors, and stolen goods.

This heterogeneous mix allows us to fine-tune Venn's malicious transaction detection system, ensuring broad and effective coverage.

{% hint style="info" %}
As we progress through iterations cycles, we will be releasing more information about the results of each phase and the hacked protocols that have been used for the tests
{% endhint %}

## Support

We deeply appreciate your support and commitment to our vision of a secure Web3.\
For any assistance during the integration process or after, our technical support team is ready to help.

* **Join Venn Discord - T**o access support, join the Venn Discord community using the link below:\
  [Venn Discord - Join Here](https://discord.gg/97cg6Qhg)<br>
* **Open a Support Ticket -** Once in the Discord server, navigate to the `#support-ticket` channel and open a ticket. Our team will respond promptly to assist you

[^1]: Malicios transactions flagged by Venn as valid

[^2]: Valid transactions that are flagged by Venn as malicious

[^3]: Valid transactions as well as hacking transactions


# Troubleshooting

Before creating an issue with Venn support, please check this page to see if you can resolve your issues. If you are still stuck, please open a support ticket.


# Staking


# Security Teams

## **What is a Security Team in the Venn Network?**

Security teams in the Venn Network consist of developers, researchers, and security companies that focus on identifying and preventing malicious transactions. They offer customized security models by integrating their unique threat models into the Venn infrastructure.

***

## **Types of Security Teams**

### **Audit Companies**

Specialize in conducting thorough audits to identify bugs and vulnerabilities in smart contracts, applications, and infrastructure.

**What Venn Enables**: While audit companies are crucial in the pre-deployment phase, it is common for developers to continue updating and evolving their projects after the initial audit. This ongoing development can render the original audit less relevant post-deployment. Venn enables audit companies to extend their capabilities into the post-deployment phase, offering continuous protection for their clients and the Venn ecosystem. With Venn, audit companies can provide post-deployment protection through custom environment checks and tailored solutions, integrating their off-chain expertise into on-chain security measures to ensure comprehensive and ongoing security.

### **Monitoring and Detection Platforms**

Focus on real-time monitoring and threat detection to promptly identify and respond to security incidents.

**What Venn Enables**: Monitoring and detection platforms excel at identifying and alerting for security events. However, their ability to actively intervene and prevent incidents in real-time during the TX execution phase has been limited. Venn transforms this capability by enabling these platforms to detect, mitigate, and stop malicious activities as they occur. By integrating with Venn’s infrastructure, monitoring and detection platforms can integrate their detection models using Venn SDK into their node client. This allows them to offer their clients immediate and adequate security measures during TX execution time.

### **Formal Verification Teams**

Focus on mathematically proving the correctness of smart contracts and protocols to ensure they behave as intended.

**What Venn Enables**: Venn allows formal verification teams to integrate their proofs directly into their node client using Venn's SDK for security infrastructure. Venn enables FV teams to offer their clients post-deployment and ongoing protection, providing custom and tailored validation solutions that adapt to evolving threats and maintain the integrity of verified protocols over time.

### **Security Researchers**

Focus on uncovering new vulnerabilities and developing security best practices to safeguard the blockchain ecosystem. They delve into the complexities of cryptographic algorithms, consensus mechanisms, and smart contract security to identify potential weaknesses.

**What Venn Enables**: Venn provides security researchers with a robust platform to test and deploy their findings in a live environment. This capability allows them to validate their research and directly contribute to network security by implementing advanced security measures. Researchers can leverage Venn to transition their off-chain discoveries into on-chain protections, ensuring that their innovative solutions have immediate and tangible impacts on web3 security.

### **Economic Researchers**

Specialize in modeling market risks, optimizing economic incentives, and driving sustainable growth for protocols. These teams utilize quantitative analysis and simulation techniques to provide insights into protocol performance and economic mechanisms.

**What Venn Enables**: Venn empowers economic researchers to bring their advanced models for market risk, economics, and on-chain activity directly into the Venn network. By integrating with Venn, these researchers can apply their off-chain analyses to on-chain operations, ensuring that economic strategies are implemented in real-time. This integration allows economic researchers to offer tailored solutions for protecting protocol incentives and managing economic and governance risks.

{% hint style="info" %}
Venn is currently operating in a permissioned mode. To join Venn as a Security Team, please [contact us](https://www.venn.build/join/security-team) to express your interest and learn more about the requirements and process.
{% endhint %}

***

## **Rewards**

Rewards for Security Teams are distributed based on contribution. Detailed information can be found in the economic section of the [Litepaper](/venn-network/litepaper).


# Build Custom Detector

This guide walks you through building your custom detector on the Venn Network. Use this as a starting point to implement your detection logic which will secure transactions on the Venn Network.

{% hint style="info" %}
This guide is intended for developers, security researchers, and security teams who want to integrate their unique threat models into the Venn ecosystem or develop new security models.
{% endhint %}

## Overview

### To build a custom detector on Venn, you will need to:

1. Clone (or fork) **venn-custom-detection** Template.
2. Implement your **detection logic**.
3. **Test** that your detector responds with detection results.
4. **Deploy** your detector and connect it to your [Venn node client.](/venn-network/getting-started/node-operators)

{% hint style="info" %}
You can choose to become a [Venn node operator ](/venn-network/getting-started/node-operators)and run your detection model on your node, or connect with other Venn node operators that will run your detection model.&#x20;
{% endhint %}

{% hint style="info" %}
If you need help connecting with a Venn node operator to run your detector, please [contact us](https://www.venn.build/join/security-team?_gl=1*1i862le*_ga*NDE3OTA5NDg3LjE3MzkyOTEyMjA.*_ga_Y3G93T90DW*MTc0MTY5MjM4NS4xMjEuMS4xNzQxNjk3MTAzLjU3LjAuMTI5Njc1NDc.*_ga_CEBTDZ1167*MTc0MTY5MjM4NS4xMjEuMS4xNzQxNjk3MTAzLjAuMC4w). We’re here to help you find a trusted partner so you can deploy your detection model.
{% endhint %}

***

## Quick Start

### **Step 1: Clone the Repository**

Begin by cloning or forking the [Venn Custom Detector Boilerplate](https://github.com/ironblocks/venn-custom-detection).

```bash
git clone https://github.com/ironblocks/venn-custom-detection.git
cd venn-custom-detection
```

### **Step 2: Install Dependencies**

Install the required packages using your preferred package manager:

```bash
yarn install
# or
npm install
```

### **Step 3: Run in Development Mode**

Start the detector locally to begin working on your detection logic:

```bash
yarn dev
# or
npm run dev
```

{% hint style="info" %}
Your detector service will start (default on port 3000) and be ready to receive detection requests.
{% endhint %}

***

## Detector Service Overview

The core of your custom detector logic is the `DetectionService`, found in `src/modules/detection-module/service.ts`. This service implements a `detect` method that receives a `DetectionRequest` (an enriched view of an EVM transaction) and returns a `DetectionResponse`.

### Example Implementation

```typescript
import { DetectionResponse, DetectionRequest } from './dtos'

/**
 * DetectionService
 *
 * Implements a `detect` method that receives an enriched view of an
 * EVM compatible transaction (i.e. `DetectionRequest`)
 * and returns a `DetectionResponse`
 *
 * API Reference:
 * https://github.com/ironblocks/venn-custom-detection/blob/master/docs/requests-responses.docs.md
 */
export class DetectionService {
    /**
     * Update this implementation code to insepct the `DetectionRequest`
     * based on your custom business logic
     */
    public static detect(request: DetectionRequest): DetectionResponse {
        
        /**
         * For this "Hello World" style boilerplate
         * we're mocking detection results using
         * some random value
         */
        const detectionResult = Math.random() < 0.5;


        /**
         * Wrap our response in a `DetectionResponse` object
         */
        return new DetectionResponse({
            request,
            detectionInfo: {
                detected: detectionResult,
            },
        });
    }
}
```

{% hint style="info" %}
Update the `detect` method with your security logic or model to analyze transactions based on your threat model.
{% endhint %}

{% hint style="info" %}
For more details, request validation, and response structures, refer to our [API Reference Documentation](https://github.com/ironblocks/venn-custom-detection/blob/master/docs/requests-responses.docs.md).
{% endhint %}

***

## Testing Your Detector

You can simulate transactions using the [Security Sandbox](https://explorer.venn.build/toolkit/security-sandbox), a dedicated testing environment specifically designed to evaluate your custom detection model. With the Security Sandbox, you can simulate any transactions from the preferred chains or choose past hacks to test against your detection model.&#x20;

Or

You can simulate transactions by sending them directly to `DetectionRequest` payload (refer to our [API Reference](https://github.com/ironblocks/venn-custom-detection/blob/master/docs/requests-responses.docs.md) for details) and evaluate your custom detection model in the returned `DetectionResponse`.

***

## Deploy to Production

When you’re ready to deploy your detector service, choose from one of the following options:

### Manual Build & Deployment

1. **Build the Service:**

   ```bash
   yarn build
   # or
   npm run build
   ```
2. **Start the Service:**

   ```bash
   yarn start
   # or
   npm run start
   ```

### Using Docker

Build a Docker image for your detector:

```bash
docker build -f Dockerfile . -t my-custom-detector
```

*Deploy the Docker container to your production environment as needed.*

{% hint style="success" %}
That's it! Welcome to Venn. 🎉&#x20;
{% endhint %}


# Safe Guard

## Introduction

Venn Safe Guard is a decentralized security-validation layer for Safe (Gnosis Safe) multisig accounts. By integrating seamlessly into your Safe transaction workflow, Venn ensures that every transaction undergoes rigorous decentralized security validation, thereby reducing the risk associated with malicious or unauthorized multisig operations.

***

### Why Choose Venn Safe Guard?

* Zero UI Trust: Independent validation - immune to compromised front-ends.
* Decentralized and vendor-neutral: no single points of failure or risky dependencies on third parties.
* End-to-End Validation: Continuous validation before, during, and after execution.

***

### What Venn Safe Guard Protects Against?

* Compromised Signers
* Compromised Interfaces (UI Hijack)
* Privilege Escalation
* Silent Backdoor Installation
* Malicious Admin Batching
* Fallback handlers Hijacking

***

## **How it Works**

Venn Safe Guard is designed as a modular Safe Guard, seamlessly integrated into your existing Safe multisig account. Safe Guard is a specialized smart contract officially supported by Safe, created to add customized validation logic for the lifecycle of Safe transactions (see [Safe Guard documentation](https://docs.safe.global/advanced/smart-account-guards)).

### **Step 1: Build Your Transaction**

* Safe owners or admins build transactions using two options:
  * **Venn API (for local/programmatic builds)**
  * **Venn Transaction Builder UI**.

{% hint style="info" %}
*Transaction format matches Safe's native structure and supports multicalls/batches, which mirrors Safe’s native transaction-building and t*ransaction Servic**e** *flow.*
{% endhint %}

### **Step 2: Decentralized Security Validation**

* The built transaction is automatically sent to the [**Venn Decentralized Validation Network**](/#what-is-venn).
* Independent **Tier-1 security operators** evaluate transactions against your security policy.
* Venn’s [consensus](/venn-network/consensus-model#introduction-to-the-venn-consensus-model) aggregates operators' votes to decide if the transaction is secure and allowed to proceed or malicious and blocked from execution.

{% hint style="info" %}
*You can consume Venn Security Validation either using the Venn Safe Guard API (for programmatic or local use), or through the dedicated Venn UI, which handles the validation process automatically behind the scenes.*
{% endhint %}

### **Step 3: Submission to Safe Queue**

* Approved transactions (including Venn's validation signature) are submitted to the Safe multisig transaction queue.
* Safe signers proceed to approve transactions normally, just like **regular Safe transactions.**

### **Step 4: On-Chain Guard Validation**

* When signers trigger on-chain execution, the **Venn Safe Guard** contract performs:
  * **Pre-Execution Check:** The Guard extracts and stores the transaction’s original bytecode for comparison.
  * **Execution-Time Validation:** On-chain verification of Venn’s aggregated signature and operator consensus, validating transaction authenticity and integrity.
  * **Post-Execution Check:** Confirms executed transaction bytecode matches pre-approved bytecode.

{% embed url="<https://link.excalidraw.com/readonly/cs016hEyNEHwu5HnqO3q?darkMode=true>" fullWidth="true" %}
Venn Safe Guard&#x20;
{% endembed %}

***

## Venn Guard Smart Contract

The **Venn Guard smart contract** is the core on-chain component of Venn’s Safe integration. Implemented as a Safe Guard contract, it acts as a **firewall** enforcing transaction validations directly at the smart contract execution layer. The Guard interacts with Venn's decentralized network, ensuring only transactions explicitly approved by [operator consensus](/venn-network/consensus-model) can be successfully executed.

Source Code available at: [VennGuard.sol](https://github.com/ironblocks/onchain-firewall-v2/blob/main/contracts/gnosis-safe/VennGuard.sol)


# Installation

This guide will take you through adding Venn’s Guard to your Safe in 4 simple steps.

***

{% hint style="success" %}
**Early Access Support:** We currently handle the deployment and integration of Venn Safe Guard for you. You can start protecting your Safe immediately while we take care of the setup for you – contact us to get started.
{% endhint %}

## Overview

To protect your Gnosis Safe with Venn, you will need to:

1. **Download** Venn's smart contracts and install their dependencies
2. **Deploy** a new instance of the Venn Safe Guard smart contract
3. **Add** Venn Safe Guard to your Gnosis Safe
4. **Use** your Safe with the Venn Guard available interfaces (API or UI)

{% hint style="info" %}
**Note:** During this installation process, you will need to sign and execute the `setGuard()` method on your Gnosis Safe. Depending on your Gnosis Safe's signing threshold, additional signers may be required to sign the transaction before you can execute it to complete the installation.
{% endhint %}

***

## Step 1 - Download Venn's smart contracts

### Clone the Venn's Smart Contracts GitHub repo

Start by cloning our smart contracts, which will allow you to build and deploy a new instance of the Venn Safe Guard.

```sh
git clone https://github.com/ironblocks/onchain-firewall-v2
```

*This command clone Venn's Smart Contracts to the a new folder named \`onchain-firewall-v2\`*

### Install dependencies

Run the following command to install the project's dependencies:

```sh
cd onchain-firewall-v2
npm install
```

*This command will install all the required to complete this installation guide*

## Step 2 - Deploy a new instance of the Venn Safe Guard

### Create a configuration file

First, you'll need to create a `.env` file based on the existing `.env.example`, and modify it's configuration to fit your setup.

```sh
cp .env.example .env
```

*This command creates a new copy of the configuration file at \`.env\`. In the steps below we'll update some of the configurations to your needs.*

### Configuring the guard

Open the newly created `.env` file, and find the `Venn Safe Guard` section which looks like this:

```sh
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# Venn Safe Guard                                                               #
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

# Bypass Transactions Timelock (in seconds)
#
BYPASS_GUARD_WAIT_TIME = 

# Safe Address
# The Safe address that the Guard is protecting
#
SAFE_ADDRESS = 
```

* Paste the address of your `Gnosis Safe` in the `SAFE_ADDRESS` field
* Set the desired timelock period for [Bypass Transactions](https://docs.venn.build/venn-network/getting-started/venn-safe-guard/bypass-mechanism) in the `BYPASS_GUARD_WAIT_TIME` field

{% hint style="warning" %}
For **Production** deployments, the recommended timelock duration is one day, which is `86400` seconds
{% endhint %}

{% hint style="warning" %}
For security reasons, these configuration **cannot** be changed once the Venn Safe Guard is deployed.\
Any needed changes will require a new deployment of the Venn Safe Guard.
{% endhint %}

*These configurations create a one-to-one relationship between the Venn Safe Guard and your Gnosis Safe - so that the guard cannot be used by any other Gnosis Safe.*

### Configuring your Private Key

Open the newly created `.env` file, and find the `General Configs` section which looks like this:

```sh
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# General Configs                                                               #
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

# Private Key (i.e. deployer)
#
# Anvil Test Account 1 = ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
#
PRIVATE_KEY = 
```

* Paste your private key onto the `PRIVATE_KEY` field

{% hint style="info" %}
This Private Key will be used by Hardhat to deploy a new instance of the Venn Safe Guard, and will be given the `ADMIN_ROLE` on the newly deployed Venn Safe Guard contract.
{% endhint %}

### Configuring EtherScan

{% hint style="info" %}
**Note**: This step is optional
{% endhint %}

We use hardhat-verify under the hood to verify newly deployed smart contracts, which uses Etherscan's API. To enable verification, add your Etherscan API as shown below:

```sh
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# General Configs                                                               #
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

...

# Etherscan API Key
# Used by Hardhat for verifying contracts
#
ETHERSCAN_KEY = 
```

* Paste your Etherscan API key into the `ETHERSCAN_KEY` field

### Deploy the Venn Safe Guard

Run the following command to deploy a new instance of the Venn Safe Guard smart contract:

{% hint style="warning" %}
**Note:** If you want to skip contract verification or if you have not configured an `ETHERSCAN_KEY` above, omit the `--verify` flag
{% endhint %}

```sh
npx hardhat migrate --namespace "venn/Guard" --network holesky --verify --only 1
```

Once completed, you should see the address of the newly deployed Venn Safe Guard shown as follows:

<figure><img src="/files/GXNf91gxgyd001vltmm8" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** You can update the `--network` flag to other networks. See the file `hardhat.config.ts` for more info.
{% endhint %}

*This command deploys a new instance of the Venn Safe Guard.*

***

## Step 3 - Add Venn Safe Guard to your Gnosis Safe

### Call the setGuard() method

To add the newly deployed guard to your Gnosis Safe, you'll need to call the `setGuard()` method, passing in the address of the Venn Safe Guard from the previous step.

{% hint style="info" %}
**Note:** As the Gnosis Safe{Wallet} UI may update from time to time, refer to the official Safe documentation here on using the UI to add a Guard to your Safe:

<https://help.safe.global/en/articles/40804-add-a-transaction-guard>
{% endhint %}

{% hint style="warning" %}
**Note:** The `to` address of this transaction should be the address of your Gnosis Safe, as this transactions calls its `setGuard()` method to add the Venn Safe Guard to it
{% endhint %}

<figure><img src="/files/b7e60BHeFHcqpSZIBhUe" alt=""><figcaption></figcaption></figure>

***

## Step 4 - Use your Safe with the Venn Guard available interfaces (API or UI).

With Venn Safe Guard now deployed, you can continue to build, sign, and execute Safe transactions exactly as before - now every Safe transaction will pass through Venn’s Guard security validation.&#x20;

### Choose the interface that fits your Safe workflow:

#### A. **Venn Safe API (for local/programmatic Safe interactions)**&#x20;

The Venn Guard Transaction Validation API enables automatic transaction validation through Venn’s decentralized security network. It accepts standard transactions and returns a JSON response that includes Venn's security validation signature, which is ready to be uploaded to any Safe UI or used in local flows.

{% hint style="info" %}
Start using the Venn Guard API using this [API Reference](/venn-network/getting-started/safe-guard/transaction-validation-api)
{% endhint %}

#### **B. Venn Safe Guard UI**

The Venn Guard web interface enables you to build, validate, upload, download, sign, and submit your Safe transactions with the familiar Safe UI experience, closely mirroring the native Gnosis Safe platform. Additionally, you can perform administrative operations such as adding, removing, or editing signers, adjusting thresholds, and more.

{% hint style="info" %}
Load your Safe account and start using the [Venn Guard platform](https://explorer.venn.build/toolkit/venn-safe-guard)
{% endhint %}

***

## Supported Networks

<table data-header-hidden><thead><tr><th width="45.421875" data-type="number"></th><th width="149.9375">Chain</th><th>Mainnet</th><th>Testnet</th></tr></thead><tbody><tr><td>1</td><td>Ethereum</td><td>Mainnet (1)</td><td></td></tr><tr><td>2</td><td>Base</td><td>Base Mainnet (8453)</td><td>Base Sepolia (84532)</td></tr><tr><td>3</td><td>Arbitrum</td><td>Arbitrum One (42161)</td><td></td></tr><tr><td>4</td><td>BSC</td><td>BSC (56)</td><td></td></tr><tr><td>5</td><td>Polygon</td><td>Polygon (137)</td><td></td></tr></tbody></table>


# Transaction Validation API

The Venn Guard Transaction Validation API enables automatic transaction validation through Venn’s decentralized security network. It accepts standard user transactions and returns a JSON that is ready for upload to any Safe UI.

## API

{% hint style="success" %}
**v1.0.4 \[STABLE]**
{% endhint %}

### Request

<table data-header-hidden><thead><tr><th width="162.15625"></th><th></th></tr></thead><tbody><tr><td>URL</td><td><pre><code>https://safe-operator1-signer.venn.build/batch/sign
</code></pre></td></tr><tr><td>METHOD</td><td><pre><code>POST
</code></pre></td></tr></tbody></table>

**Body**

```typescript
{
    chainId: number,
    safeAddress: string,
    transactions: [
      {
        to: string
        value: string
        data: string
      }
    ]
}
```

### Response

If all of the transactions passed validation, the API will respond with a new Safe Transaction Batch that can be uploaded into any Safe UI.

If one or more of the transactions fail validation, the API will respond with an error.

{% hint style="info" %}
In both cases, the `STATUS` of the response is `200 OK`
{% endhint %}

#### Success

```typescript
{
    requestId: string,
    data: {
        version: string,
        chainId: string,
        createdAt: number,
        meta: {
            name: string,
            description: string,
            txBuilderVersion: string,
            createdFromSafeAddress: string,
            createdFromOwnerAddress: string,
            checksum: string
        },

        transactions: [
            // Venn Signature Transaction
            {
                to: string,
                value: string,
                data: string
            },


            // Original User Transactions
            {
                to: string,
                value: string,
                data: string
            }
        ]
    },
    status: string
}
```

#### Error

```typescript
{
    requestId: string,
    isError: boolean,
    message: string,
    status: string
}
```

## Code Example

```typescript
import axios from "axios";

// Your Safe Address
const SAFE_ADDRESS = "0x..." 

// 1st transaction in the batch
const userTransaction1 = {
    to: "0x...",
    value: "0",
    data: "0x...",
    safeAddress: SAFE_ADDRESS,
};

// 2nd transaction in the batch
const userTransaction2 = {
    to: "0x...",
    value: "0",
    data: "0x...",
    safeAddress: SAFE_ADDRESS,
};

// Validating and signing the transactions with Venn
const response = await axios.post(
    "https://operator1-signer.venn.build/batch/sign",
    {
       transactions [userTransaction1, userTransaction2],
       safeAddress: SAFE_ADDRESS
    }
);

console.log(response.data):
// Transaction Batch JSON
// {
//    ...
//    transactions: [
//       <Venn's Approving Signature Tx>,
//       <User Tx 1>,
//       <User Tx 2>,
//    ]
// }


```


# Bypass Mechanism

Bypass Mechanism Purpose

The bypass functionality enables you to execute transactions that don't meet the normal Venn Guard validation requirements when:

* Emergency situations require actions that don't conform to standard rules
* Technical issues prevent normal transaction patterns
* Unanticipated scenarios arise that were unknown during the initial guard setup

***

## How It Works

The bypass mechanism uses a **timelock approach**:

1. Safe owners propose and sign a transaction
2. A bypass request is submitted with signatures meeting the Safe threshold
3. After a waiting period (set once when the guard is deployed and configurable for up to 7 days), the transaction can be executed

This provides a security balance - allowing flexibility while preventing the immediate execution of potentially high-risk transactions.

***

## Select a Bypass Path

<details>

<summary>Bypass via Venn UI (Recommended)</summary>

{% hint style="info" %}
**Prefer a no-code path?** You can complete the bypass flow using a dedicated UI - no scripts or Etherscan interaction needed.
{% endhint %}

#### Prerequisites

* Venn Guard is installed on your Safe.
* You’re connected with a Safe owner wallet to the [Venn UI](https://explorer.venn.build/toolkit/venn-safe-guard).

#### Steps:&#x20;

1. **Open the Venn platform** and navigate to the [Guard Dashboard](https://explorer.venn.build/toolkit/venn-safe-guard).
2. **Create or import the transaction:**\
   • Build the transaction in Venn’s Tx Builder, or\
   • Upload an existing transaction to Venn, or\
   • Use the Send Tokens page for simple transfers.
3. **Select transaction type = Bypass**\
   In the Venn UI **(**&#x62;efore you sign the transaction), select the transaction type as <kbd>Bypass</kbd>.
4. **Navigate to the** [**Bypass page**](https://explorer.venn.build/toolkit/venn-safe-guard/bypass-guard)**,** and complete these steps:

* **Signers confirmations**: Other owners sign the transaction as they normally would in the Safe interface.
* **Send Bypass Transaction**: Once the threshold is met, you can send the Bypass Transaction.
* **Wait for the timelock countdown to finish**.
* **Execute the Transaction** once the timelock finishes.

</details>

<details>

<summary>Bypass via Direct Contract Calls (Programmatic)</summary>

#### Step 1: Create and Sign the Transaction

Create the transaction you want to bypass through the Safe UI:

* Specify the transaction details (recipient, value, data, etc.)
* Have the required number of owners sign it

{% hint style="warning" %}
&#x20;**Important**: Don't execute the transaction yet - keep it in the transaction queue by selecting:\ <kbd>No, later</kbd> option, and then you can sign the transaction.
{% endhint %}

#### Step 2: Collect Required Signatures

* Ensure enough Safe owners have signed the transaction to meet the Safe's threshold requirement.
* Signers can add their signature just as they normally would - through the Safe UI, or via API integration with the Safe Transaction Service.

#### Step 3: Submit Bypass Request

* Call the ⁠`bypassGuard()` function on the VennGuard contract with the following parameters copied from the queued transaction:

{% hint style="success" %}
Tip: You can find the address of the guard from the Safe UI under **Settings --> Modules**
{% endhint %}

<table data-header-hidden data-full-width="false"><thead><tr><th valign="top"></th><th valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top"><strong>Parameter</strong></td><td valign="top"><strong>Description</strong></td><td valign="top"><strong>Where to Find It</strong></td></tr><tr><td valign="top">to</td><td valign="top">Destination address</td><td valign="top">Transaction details in Safe UI</td></tr><tr><td valign="top">value</td><td valign="top">ETH amount (in wei)</td><td valign="top">Transaction details in Safe UI</td></tr><tr><td valign="top">data</td><td valign="top">Transaction calldata</td><td valign="top">Transaction details in Safe UI (0x for no data)</td></tr><tr><td valign="top">operation</td><td valign="top">Call type (0=Call, 1=DelegateCall)</td><td valign="top">Usually 0 (Call)</td></tr><tr><td valign="top">safeTxGas</td><td valign="top">Gas for the Safe transaction</td><td valign="top">Transaction details in Safe UI</td></tr><tr><td valign="top">baseGas</td><td valign="top">Base gas amount</td><td valign="top">Transaction details in Safe UI</td></tr><tr><td valign="top">gasPrice</td><td valign="top">Gas price for the transaction</td><td valign="top">Transaction details in Safe UI</td></tr><tr><td valign="top">gasToken</td><td valign="top">Token used for gas payment</td><td valign="top">Transaction details in Safe UI (0x0 for ETH)</td></tr><tr><td valign="top">refundReceiver</td><td valign="top">Address to receive gas refund</td><td valign="top">Transaction details in Safe UI</td></tr><tr><td valign="top">signatures</td><td valign="top">Collected owner signatures</td><td valign="top">Transaction details in Safe UI</td></tr></tbody></table>

* To send this `bypassGuard()`transaction, you could either use Etherscan's Write Contract functionality or write a custom script interacting with the guard contract.

#### Step 4: Wait for the Time-Lock Period

After submitting the bypass request, you must wait for the configured ⁠`bypassGuardWaitTime` to pass. This period is set during guard initialization, cannot be changed afterward, and cannot exceed 7 days.

#### Step 5: Execute the Transaction

Once the waiting period has elapsed:

1. Return to the Safe UI
2. Find the queued transaction
3. Execute it normally

{% hint style="success" %}
The guard will now recognize it as a bypassed transaction and allow execution.
{% endhint %}

#### Troubleshooting

<table data-header-hidden data-full-width="false"><thead><tr><th valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top"><strong>Issue</strong></td><td valign="top"><strong>Solution</strong></td></tr><tr><td valign="top">Error: <code>bypassGuard already called</code></td><td valign="top">A bypass request has already been submitted for this transaction. You may proceed to execute the transaction as normal</td></tr><tr><td valign="top">Transaction still fails after waiting</td><td valign="top">Verify the wait time has fully elapsed and the bypass request transaction parameters exactly match the proposed transaction parameters</td></tr><tr><td valign="top">Signatures rejected</td><td valign="top">Ensure signatures meet the Safe's threshold and are properly formatted</td></tr></tbody></table>

#### Emitted Events

The bypass mechanism emits the following events:

<table><thead><tr><th>Event</th><th>Signature</th><th>Description</th></tr></thead><tbody><tr><td><strong>Bypass Guard</strong></td><td><pre class="language-solidity"><code class="lang-solidity">BypassGuard(
   bytes32 safeTxHash,
   uint256 initTime
)
</code></pre></td><td>Emitted when a <strong>Bypass Request</strong> transaction was submitted to the guard <em>(see</em> <a href="#step-3-submit-bypass-request"><em>Step 3</em></a> <em>above)</em></td></tr><tr><td><strong>Transaction Bypassed</strong></td><td><pre class="language-solidity"><code class="lang-solidity">TransactionBypassed(
    bytes32 safeTxHash
)
</code></pre></td><td>Emitted when a <strong>Bypass Transaction</strong> was <strong>Executed</strong> on chain <em>(see</em> <a href="#step-5-execute-the-transaction"><em>Step 5</em></a> <em>above)</em></td></tr></tbody></table>

</details>

***

## Technical Details

The bypass mechanism works through these key processes:

**Transaction Identification**\
The guard calculates a unique hash for each transaction based on its parameters

**Bypass Registry**\
Stores the timestamp when a bypass was initiated for each transaction hash

**Time Verification**\
During transaction execution, the guard checks if:

1. The transaction has a registered bypass request
2. The required wait time has elapsed since the bypass was initiated

***

## Security Considerations

* The bypass mechanism requires signatures meeting the Safe's threshold
* The mandatory waiting period provides time to detect and react to unauthorized bypass attempts
* Safe owners should be notified when bypass requests are submitted
* Monitor bypass requests carefully - they circumvent normal security controls
* Consider setting a longer wait time for higher-value Safes

***


# Disarm Guard Mechanism

## Disarm Guard Purpose

In rare emergency situations, you might need to remove the guard from your wallet and execute a transaction immediately. While the [bypass mechanism](/venn-network/getting-started/safe-guard/bypass-mechanism) offers a time‑locked way to skip Venn validation, it still requires a waiting period.

The **Disarm Guard** is an immediate admin operation that disables and deletes the Guard from your safe, allowing you to reset your configuration to its original state without the Venn Guard connected to it.&#x20;

***

## Understanding Disarm Guard Mechanism

* The 'Disarm Guard' is an **optional** **capability** you can set up when deploying the Venn Guard.
* When deploying the guard, you will need to set a **dedicated and separate wallet** (ideally a separate multisig or cold wallet) that has the authority to disarm the guard.
* When activated, the 'Disarm Guard' signer calls the guard’s disarm function (a call to a  `setEnabled(false)` method, only callable by the Guard's Admin Role). This call temporarily disables the guard from on your Safe
* You can always rearm the guard by calling the `setEnabled(true)`&#x20;

{% hint style="info" %}
**How to find your guard address**: In the [Safe web interface](https://app.safe.global/settings/modules), open your Safe and go to Settings → Modules (or Advanced Settings in version 3.13.0 and later). There you’ll see the transaction guard listed with its contract address and a copy button.
{% endhint %}

***

## How to Use Disarm Guard

### Using a Cold Wallet

When using a cold wallet, you could either use Etherscan's Write Contract functionality or write a custom script interacting with the guard contract.

Step 1: Create a new transaction that calls the  ⁠`setEnabled(false)` function on the guard

Step 2: Send the transaction (via Etherscan, or custom scripts)

Step 3: Verify that the guard is disarmed by reading the `enabled` property, which will now be set to `false`&#x20;

{% hint style="info" %}
You can now execute your emergency transactions through your Safe, without Venn verification.\
Once you're done, call the same function to rearm the guard with `setEnabled(true)`.
{% endhint %}

### Using a Multisig Account

When using a multisig account, you first build the transaction that calls  `setEnabled(false)`  so that all of your multisig account signers can sign the transaction, before executing it.

Step 1: Create a new transaction that calls the  ⁠`setEnabled(false)` function on the guard

Step 2: Sign the transaction, and have all other required signers review and sign the transaction

Step 3: Execute the transaction on your multisig account&#x20;

Step 4: Verify that the guard is disarmed by reading the `enabled` property, which will now be set to `false`&#x20;

{% hint style="info" %}
You can now execute your emergency transactions through your Safe, without Venn verification.\
Once you're done, call the same function to rearm the guard with `setEnabled(true)`.
{% endhint %}

***

## Security considerations

* **Use only in emergencies** – Disarming the guard removes all security validation and exposes your Safe to the full risks Venn is designed to mitigate. Do not use this mechanism for routine operations.
* **Separate signing keys** – Keep the Disarm Guard wallet separate from everyday Safe signers. Ideally, it should be a higher‑threshold multisig or a cold wallet stored offline so that it cannot be accessed casually.
* **Monitor usage** – Set up alerts so that all Safe owners are notified whenever the guard is disarmed.&#x20;
* **Restore protection** – After using the Disarm Guard, reinstall the guard as soon as possible. Avoid leaving the Safe unguarded by Venn.


# Use cases

## Introduction

Venn Safe Guard is designed to protect a wide range of Safe users, from corporate treasuries and DeFi protocols to DAOs. This page outlines typical Safe activities and explains different use cases for Venn’s Safe Guard.&#x20;

## Use cases&#x20;

### Treasury and high‑value operations

Asset managers, treasuries, exchanges, custodians, and those controlling significant funds through Safe multisigs face high risks. High-value transfers are prime targets for hackers; this is why a standard multisig threshold is not sufficient when attackers can modify transaction details in real time (e.g., the Bybit exploit in Feb '25 drained $1.5B by spoofing the signing interface and compromising signer devices).&#x20;

Venn Safe Guard doesn’t simply monitor your wallet - it **enforces** pre, during, and post‑execution validation. **Before** a transaction reaches your Safe queue, a decentralized network of independent validators simulates it off‑chain and votes on its legitimacy, and only secure transactions receive a consensus signature that will enable them to be executed later. **During** execution, the Guard checks that this consensus signature is present and that the transaction’s bytecode matches exactly what was validated. **After** execution, it confirms that nothing has changed. This end-to-end validation prevents **Compromised Interfaces and man-in-the-middle modifications** at any stage.

### Smart Contract operations

DeFi protocols, rollups, and bridge contracts that use Safe multisig for contract upgrades, privileged function calls, and on-chain operations. These admin actions can create attack vectors, such as malicious upgrades or delegate calls, which may install silent backdoors, hijack fallback handlers, or escalate privileges.

Venn Safe Guard protects protocol development teams by simulating and verifying the exact bytecode of every upgrade or admin call through the Venn network. If the executed bytecode differs from the validated version or contains a malicious call, the Guard blocks the execution on-chain. This ensures that only authorized, reviewed, and secure contract changes are deployed, preventing common exploit routes.

### Governance operations

Boards, councils, and DAOs use Safe to pass decisions, ranging from grant approvals to parameter changes. Non‑technical signers and time pressure make governance vulnerable to social engineering and UI spoofing attacks.&#x20;

Venn Safe Guard validates every governance proposal is simulated and validated by independent security operators before entering the Safe queue. Only transactions that pass consensus validation can be executed, preventing malicious approvals.


# Venn Wallet RPC

## Introduction to Venn RPC <a href="#introduction-to-venn-playground" id="introduction-to-venn-playground"></a>

Venn RPC secures your Web3 transactions by routing every transaction through a decentralized security validation process performed by Venn security operators. If a transaction is flagged as malicious, it’s blocked before reaching the blockchain.

{% hint style="warning" %}

> ***Note:** Venn RPC currently offers **standard RPC functionality**. Security features and wallet protection are **coming soon**.*
> {% endhint %}

***

## How It Works

Switch your wallet’s RPC provider to Venn RPC on your chosen EVM network, and every transaction you initiate undergoes a robust security check.

* **Seamless Integration:**\
  Update your wallet’s settings to point to the Venn RPC URL.&#x20;
* **Real-Time Security Validation:**\
  Each transaction is immediately routed to our decentralized network of trusted Venn security operators. They perform a real-time risk assessment.
* **Customizable Protection:**\
  You can choose to opt in or out of different security features according to your comfort level. Thus, you can tailor your protection based on the types of threats you want to guard against.
* **Automatic Blocking of Risky Transactions:**\
  If Venn flags a transaction as unsafe, it is automatically blocked before it reaches the blockchain, ensuring the security of your assets and interactions.

With Venn RPC, you can enjoy a secure, worry-free Web3 experience that protects every transaction while keeping your wallet operations smooth and uninterrupted.

***

## Getting Started

Switching your wallet’s RPC provider to Venn RPC is simple and fast. Follow these steps based on your preferred network, browser, and wallet.

### **How to Change Your RPC:**

Depending on your wallet, the process of updating your RPC settings will vary. Here are the steps for each:

* **MetaMask:**\
  Follow this [step-by-step guide](/venn-network/getting-started/venn-wallet-rpc/custom-rpc-in-metamask) for Metamask custom RPC.&#x20;
* **Coinbase:**\
  Refer to [Coinbase Wallet’s guide](https://www.coinbase.com/learn/wallet/How-to-add-custom-networks-Coinbase-Wallet) for adding custom networks.
* **Rabby:**
  1. Open the Rabby extension and click **“More”** at the bottom right of the page.
  2. Click **“Custom RPC”**.
  3. Click **“Add RPC”**.
  4. Paste the Venn RPC URL for the selected network. Then click **“Save”.**

{% hint style="info" %}
**Tip**: You can change to **Venn RPC** using the [Venn Wallet firewall UI](https://explorer.venn.build/toolkit/wallet-firewall). Select your desired networks in the Venn interface to automatically switch to Venn RPC—no extra wallet configuration needed.
{% endhint %}

### **Switching to Venn-RPC on a Supported Network**

<table><thead><tr><th width="171">Network Name</th><th width="319">RPC URL</th><th width="98">Chain ID</th><th>Currency Symbol</th><th>Block Explorer URL</th></tr></thead><tbody><tr><td><strong>BNB Mainnet</strong></td><td><p></p><pre><code>https://rpc.venn.build/bnb
</code></pre></td><td>56</td><td>BNB</td><td><a href="https://bscscan.com">https://bscscan.com</a></td></tr><tr><td><strong>Ethereum Mainnet</strong></td><td><p></p><pre><code>https://rpc.venn.build/ethereum
</code></pre></td><td>1</td><td>ETH</td><td><a href="https://etherscan.io">https://etherscan.io</a></td></tr></tbody></table>

### Supported Browsers

* Chrome
* Brave&#x20;
* Firefox

### Supported **Wallets:**

* MetaMask
* Rabby
* Coinbase

***

{% hint style="warning" %}
***Note:** Venn RPC currently offers **standard RPC functionality**. Security features and wallet protection are **coming soon**.*
{% endhint %}

***


# Custom RPC in MetaMask

This page provides you with step-by-step guidance on configuring a custom network RPC in MetaMask.

{% hint style="info" %}
**Note:** MetaMask’s interface and settings may be updated over time, so we recommend referring to [MetaMask’s official documentation](https://support.metamask.io/configure/networks/how-to-add-a-custom-network-rpc/) for the latest guide.
{% endhint %}

## Step 1 - Press on the 'Network' Dropdown&#x20;

<figure><img src="/files/4zsO6v6K4IhRXBPaOneA" alt="" width="353"><figcaption></figcaption></figure>

***

## Step 2 - Press on the selected network setting (3 dots)

<figure><img src="/files/SJDEDDgDysUWLUSyuEd9" alt="" width="356"><figcaption></figcaption></figure>

***

## Step 3 - Select the 'Default RPC URL' dropdown&#x20;

<figure><img src="/files/iw9iB4STi4cH4cvNwhgf" alt="" width="356"><figcaption></figcaption></figure>

***

## Step 4 - Press 'Add RPC URL'

<figure><img src="/files/rDOmyRVldKXIEawFfxgt" alt="" width="356"><figcaption></figcaption></figure>

***

## Step 5 - Paste Venn-RPC URL for the selected Network&#x20;

### Supported Networks:

<table><thead><tr><th width="232">Network Name</th><th>RPC URL</th></tr></thead><tbody><tr><td><strong>Ethereum Mainnet:</strong></td><td><p></p><pre><code>https://rpc.venn.build/ethereum
</code></pre></td></tr><tr><td><strong>Holesky Testnet</strong></td><td><p></p><pre><code>https://rpc.venn.build/holesky
</code></pre></td></tr><tr><td><strong>BNB Mainnet</strong></td><td><p></p><pre><code>https://rpc.venn.build/bnb
</code></pre></td></tr><tr><td><strong>BNB Testnet</strong></td><td><p></p><pre><code>https://rpc.venn.build/bnb-testnet
</code></pre></td></tr></tbody></table>

<figure><img src="/files/n3KC6dQVjDoky0eQew4z" alt="" width="356"><figcaption></figcaption></figure>

***

## That's it! Your custom RPC is now set up and ready to use. :tada::rocket:

{% hint style="warning" %}
***Note:** Venn RPC currently offers **standard RPC functionality**. Security features and wallet protection are **coming soon**.*
{% endhint %}


# Explorer

## Introduction to Venn Testnet Explorer

The Venn Testnet Explorer is designed to provide transparency, traceability, and insights into the Venn network’s activities, both on-chain and off-chain. It allows dApps, developers, and protocol end-users to view real-time data across the Venn testnet. Venn Explorer offers a user-friendly interface for searching and interacting with the Venn ecosystem.

## Use Cases

### 1. Transaction View

The Transaction View shows the most recent 25 transactions with essential details such as transaction security status, hash, sender, recipient, chain, and time. Quickly see whether a transaction was approved, rejected, or reverted by the network.

### 2. Expanded Transaction View

Expand specific transactions for detailed information, including block details, operators voting results, and a list of node operators. This allows you to investigate how the transactions were handled and analyze the decision-making process behind each transaction.

### 3. Filtering

Filter by transaction security status (Executed, Firewall Reverted, Venn Rejected, Venn approved), helping you focus on transactions with specific outcomes.

### 4. Search

Search specific transactions. Enter either a transaction hash or address into the search bar. The Explorer will retrieve all related transactions. After performing an initial search, you can add or remove addresses to broaden your search. This allows for detailed exploration of multiple transactions or activities.

### 5. Total Statistics

The Explorer displays total statistics for the Venn testnet, including the number of active protocols, operators, and total transactions.

### 6. Protocol Filter

The Protocol Filter lets you filter transactions based on specific protocols (dApps) within the Transactions View. Selecting one or multiple protocols by address or Venn policy address allows you to review transactions related exclusively to those protocols.

## Transaction Security Status&#x20;

The Venn Explorer offers a detailed view of the security status of each transaction processed through the network. This status reflects the results of Venn’s security checks and consensus validation. Below are the four possible statuses a transaction can have:

• **`Executed`**: The transaction has passed all security checks and was successfully executed on-chain.&#x20;

• **`Venn Rejected`**: The transaction was flagged as not-secure and rejected before reaching the blockchain.&#x20;

• **`Firewall Reverted`**: The firewall reverted the transaction on-chain, preventing execution.

• **`Venn Approved`**: The Venn network has approved the transaction and is preparing it for on-chain submission.

## Screenshots

### Venn Explorer’s main page:

<figure><img src="/files/MnKfB99hRNBPO5WcmGjv" alt=""><figcaption><p>Venn Explorer’s main page displays a summary of recent transactions, search bar, and Total Statistics.</p></figcaption></figure>

### Expanded transaction page:&#x20;

<figure><img src="/files/0Ekjb9SoFRMWUiYGk7fP" alt=""><figcaption><p>The expanded transaction page offers detailed transaction information.</p></figcaption></figure>


# Playground

Introduction to Venn Playground

Welcome to Venn Playground, a demo dApp on the Venn testnet that lets you explore and understand how Venn works while showcasing Venn integrations. By simulating transactions on the Holskey testnet, you can experience a range of transaction types and observe how they are validated and handled within the Venn ecosystem. Additionally, the Playground features integrations via our CLI and built-in code editor.

{% hint style="info" %}
**Tip:** Getting a Holesky Faucet. To interact with the Venn playground, you'll need Holesky testnet tokens. You can quickly get them from one of the following Holesky faucets:

* [Google](https://cloud.google.com/application/web3/faucet/ethereum/holesky)
* [QuickNode](https://faucet.quicknode.com/ethereum/holesky)
  {% endhint %}

***

## How to Play&#x20;

Follow these steps to explore the Venn Playground:

### Open the Playground:&#x20;

Access the Venn Playground at <https://explorer.venn.build/playground>

### Step 1: Connect Your Wallet

Connect your wallet to start exploring Venn Playground. This will enable you to simulate transactions.

<figure><img src="/files/h4qks2JSNf8KQHnz199S" alt=""><figcaption></figcaption></figure>

## Step 2: Integrate Venn to a demo dApp

This step guides you through setting up the Venn integration. Follow the on-screen prompts to configure your environment, ensuring your dApp communicates with the Venn ecosystem for real-time transaction processing and validation.

The integration process is broken down into the following substeps:

1. **Your dApp Contract:** explore the current state of your dApp contract.
2. **Venn Firewall Integration:** use the CLI tool to integrate Venn Firewall into your smart contract.&#x20;
3. **Venn Integration – From Venn Ready to Venn Enabled:** Enable Venn’s security features for your smart contract and connect your dApp to the Venn network.
4. **dApp Frontend SDK:** Make sure your dApp frontend is protected also by adding Venn-SDK to your dApp.

<figure><img src="/files/m3WOM7npaPFl7bgsbexG" alt=""><figcaption></figcaption></figure>

### Step 3: Simulate Different Transaction Type

Simulate 3 diffrent typs of transacitons. This will allow you to see how Venn processes and validates different transaction scenarios.&#x20;

Available Transaction Types:

1\. **Normal Transaction**: Simulate a legitimate transaction that is successfully validated through Venn. This transaction will be processed without any issues, and you’ll see it as ‘Executed’ on the Venn Explorer.

<figure><img src="/files/jEFQHxk0LAJIsRwDTwmb" alt=""><figcaption></figcaption></figure>

2\. **Malicious Transaction**: Simulate a malicious transaction that will not be validated. The Venn Explorer will show it was ‘Venn Rejected,’ and the operator voted ‘Not-Secure’ due to security risk.

<figure><img src="/files/KRllhsHNWtqT8f7Buejl" alt=""><figcaption></figcaption></figure>

3\. **Bypass Attempt**: Simulate a transaction attempting to bypass Venn by sending it directly to the protocol. The firewall will block this attempt, and the Venn Explorer will indicate that the transaction was ‘Firewall Reverted.'

<figure><img src="/files/HflCPMKPfgy4Bla8GESh" alt=""><figcaption></figcaption></figure>

### Step 4: Check Transaction Details on Venn Explorer

Discover how Venn validates your transactions. Instructions:

• Go to the Venn Explorer at <https://explorer.venn.build>

• Search your wallet address in the search bar.

• Review the status and details of your transactions.

<figure><img src="/files/9CZgQJLAvZJNvZp7T0Vd" alt=""><figcaption></figcaption></figure>

### Your Wallet and dApp information&#x20;

On the right side of the interface, you can view your wallet and dApp details, including addresses and balances, at every step in the playground. If you prefer to focus on integration, you can collapse this panel to create additional space for your code.

<figure><img src="/files/YgJpQTJ7WnrWWY81gUy5" alt=""><figcaption></figcaption></figure>


# Use Cases

***

### **Defi Protocol Security**

Integrating Venn's security infrastructure enables DeFi protocols to block malicious transactions in real-time, both on the dApp frontend and at the smart contract level. The Venn network validates each transaction, and the On-Chain Firewall receives the network's consensus to prevent malicious transactions from being processed. This ensures user funds' safety and the platform's integrity by preventing exploits and attacks on smart contract vulnerabilities, enhancing user trust and protocol reliability.

### Chains and Rollups

Chains and Rollups integrating Venn's decentralized security mechanisms can ensure transaction security before they are batched and committed to the main blockchain. The Venn network validates each transaction, and security policies are enforced at the rollup infrastructure level to prevent the processing of malicious transactions. This reduces the risk of fraud and enhances the overall security of the L2 and rollup process, ensuring that only verified transactions are included in the batches sent to the main chain. This integration can be implemented at both the sequencer and dApp level, providing flexible and robust security solutions for various components of the Layer 2 ecosystem.

### Rollup as a Service (RaaS)

Integrating Venn's security infrastructure into Rollup as a Service (RaaS) platforms offers a seamless, plug-and-play solution that RaaS providers can incorporate directly into their deployment flow. Venn provides a "decentralized security validation" plugin for sequencers, ensuring that every transaction within the rollup is thoroughly validated before being batched and committed to the main blockchain. This integration helps RaaS providers expand their offerings by providing developers with built-in, robust security features, reducing the risk of fraud and maintaining the integrity of the rollup. By leveraging Venn, RaaS platforms can deliver higher security standards, giving developers confidence that their rollup deployments are secure and compliant with best practices.

### **Smart Wallet Protection**

Smart wallets can leverage Venn's security infrastructure to ensure the safety of all user transactions and interactions. By integrating Venn, smart wallets enable end users to access advanced security features that validate each wallet interaction before the blockchain processes it. The Venn network performs thorough validation of transactions initiated by the user and those directed to the user's wallet. The On-Chain Firewall enforces security policies to prevent unauthorized access and fraudulent activities. This integration provides a secure environment for managing digital assets, ensuring that every wallet interaction is verified and safe.

### **Bridge Security**

Integrating Venn's security infrastructure into blockchain bridges enhances the security of cross-chain transactions. Venn performs thorough validation to prevent unauthorized transactions and ensures accurate data feeds to avoid Oracle manipulation. This helps maintain balance across bridges and protects against vulnerabilities like smart contract bugs. By leveraging Venn, bridge operators can ensure assets are transferred safely and reliably between different networks.

### Security Teams, Monitoring platforms, and Audit Companies

Venn's infrastructure enables monitoring platforms, auditors, whitehats, and researchers to elevate their capabilities by integrating their unique security methods, models, and algorithms into the Venn network. Using the Venn SDK, they can connect models to the network or implement them in standalone mode, opening new business opportunities by taking their models on-chain and joining the next paradigm in Web3 security. By joining the Venn network, they can actively participate in transaction validation and earn rewards for their contributions.

### **On-Chain Compliance**

Venn enables protocols to automate the enforcement of compliance policies directly on the blockchain, ensuring transactions meet regulatory requirements before being processed. This helps adhere to compliance standards such as KYC and AML to prevent fraud, ensure transparency, and enhance trust by maintaining immutable records of all compliance-related activities. Additionally, Venn reduces operational costs and complexity by simplifying the integration of compliance measures, providing a robust and flexible compliance solution for blockchain applications.

### Decentralized Physical Infrastructure Networks (DePIN)

Venn’s security framework can be integrated into Decentralized Physical Infrastructure Networks (DePIN) to protect the integrity and security of physical asset management and data exchange. DePIN networks often rely on decentralized mechanisms to manage physical resources and infrastructure, so Venn ensures that all transactions and data exchanges are thoroughly validated before processing. This helps prevent unauthorized access, fraud, and manipulation within the network, safeguarding critical physical infrastructure. By integrating Venn, DePIN networks can enhance trust and reliability in managing decentralized physical assets, ensuring that all interactions and transactions are secure and compliant with network policies.

### Real World Assets (RWA)

Integrating Venn's security infrastructure into platforms that tokenize and manage Real World Assets (RWA) enhances the security and integrity of asset transactions on the blockchain. Venn validates each transaction, ensuring that tokenized representations of physical assets are accurately and securely managed. The On-Chain Firewall enforces compliance with regulatory standards and prevents unauthorized or fraudulent activities. By leveraging Venn, platforms can offer investors a secure environment for trading and managing RWAs, maintaining trust and transparency in tokenization while adhering to legal and regulatory requirements.

### Externally Owned Accounts (EOA)

By integrating Venn's security infrastructure with Externally Owned Accounts (EOA) through dedicated MetaMask Snap or a dedicated RPC endpoint, end-users can benefit from enhanced security in their wallet interactions. Venn validates each transaction initiated from an EOA, detecting and preventing malicious activities such as phishing attacks, unauthorized access, and fraudulent transactions before they reach the blockchain. The On-Chain Firewall enforces the security policies directly at the account level, providing users real-time protection without compromising usability. This integration offers a seamless and secure user experience, ensuring that individual users can interact with decentralized applications confidently, knowing their transactions are safeguarded by Venn's robust security network.


# Roadmap

Venn's roadmap outlines our journey, highlighting key milestones, current developments, and our vision for the future. It offers a clear perspective on where we are headed, what we aim to achieve, and how our community can be involved in shaping the future of blockchain security.

***

## Chapter 1: Genesis Block-Beat  ✅

* [x] **Core Infrastructure Development:** Established the foundational infrastructure, focusing on scalability and reliability for the Venn network.
* [x] **Node Architecture:** Designed and developed the core infrastructure and node architecture.
* [x] **P2P Network**: Developed the peer-to-peer network, building a decentralized and resilient Network.
* [x] **Client SDK:** Develop the Client SDK to facilitate node integrations and interaction.

## Chapter 2: Assembly  ✅

* [x] **Operator Onboarding:** Onboard the first batch of 20 node operators.&#x20;
* [x] **Security Teams:** Onboard the first batch of tier-one security teams.
* [x] **Community Engagement:** Start assembly of Venn ecosystem and community.&#x20;
* [x] **Private Testnet:** Launched a private testnet to validate functionality and performance under controlled conditions.

## Chapter 3: Beta ⏳&#x20;

* [x] **Public Testnet:** Launch the Public Testnet for protocol and developers, enabling them to join the Venn ecosystem.
* [x] **Permissioned Mode**: Venn operates in a permissioned mode to ensure controlled onboarding of trusted operators and security teams while testing network performance and scalability.
* [x] **Fees Mechanism:** Implemented fee collection models and contracts to collect fees from Venn consumers.
* [x] **Reward Mechanism:** Established reward distribution models and mechanisms for the network participants.
* [x] &#x20;Incentive Campaign: Launch an Incentive campaign for protocol and developers and foster greater engagement with the network.
* [x] **Network Explorer Launch:** Deployed Venn network explorer, enabling exploration of security and operations in the Venn ecosystem.

## Chapter 4: Launch  🚀

* [x] **Mainnet Deployment:** Deploy Venn on mainnet.
* [ ] **Governance Framework:** A transparent and decentralized governance framework to manage the network's evolution, taking a phased approach to transitioning to a fully decentralized network.
* [ ] **Permissionless Mode**: Transition to a permissionless environment, allowing open participation from a broader range of security teams and operators.
* [ ] **Grants Program:** A grants program to support protocols, developers, security researchers, and node operators.&#x20;
* [ ] **Staking and Restaking:** Introducing features for staking and delegation, allowing participants to secure the network and earn rewards.
* [ ] **Value Rollout:** 👀

***

## What's Next?

### **Chapter 5, Expansion 🌟**

As we approach the culmination of our existing milestones, Venn is setting its sights on the future with an ambitious vision. Our forthcoming initiatives are designed to further solidify our position as a leading security layer for the blockchain ecosystem.

* **Interoperability Enhancements:** Extend Venn's capabilities to support a broader range of blockchain networks (Non-EVM).
* **Advanced & Diverse Security Modules:** Facilitate the ecosystem development and deployment of advanced and diverse security modules.
* **Decentralized Governance:** Transition towards a fully decentralized governance model, empowering our community to take a more active role in the network's evolution and decision-making.
* **Permissionless Participation:** An open ecosystem where anyone can join as node operators, security teams, and developers, allowing for broader participation and contribution to the network.
* **Global Ecosystem Growth:** Expand our global reach by onboarding more operators, security teams, and developers, fostering a vibrant and collaborative ecosystem.
* **Innovative Use Cases:** Explore and implement new use cases such as on-chain compliance, insurance mechanisms, and advanced cryptoeconomic models to leverage our security framework further.

Venn's journey is a collective effort, and we invite our community to actively participate in shaping the future of blockchain security. Together, we are building a safer, more resilient Web3 ecosystem.

***


# Governance

## **Introduction to Venn Governance**

The Venn Security Network's governance framework is designed to ensure transparency, decentralization, permissionless, and active community participation. Our phased approach to governance allows us to transition smoothly from centralized control to full decentralization, empowering the Venn ecosystem to shape the network’s future.

***

## **Governance Phases**

### **Phase 1: Centralized Governance** by the Venn Foundation (`Current phase)`

Initially, the Foundation's core team will manage the governance of the Venn Security Network to ensure its stability and security. During this phase, the core team handles all key responsibilities, including software updates, emergency fixes, and treasury management.

### **Phase 2: Security Council**&#x20;

Once the network stabilizes, a Security Council comprising selected members will take over certain governance responsibilities. The Security Council will handle emergency fixes, non-emergency maintenance, dispute resolution, and slashing events while overseeing routine operations and upgrades.

### Phase 3: Full On-Chain Governance&#x20;

In this final phase, all governance activities transition to full on-chain governance, ensuring complete decentralization and ecosystem control. The Security Council remains crucial in addressing disputes and managing slashing events while the ecosystem takes the lead in decision-making.

## Governance Phases Responsibilities

<table data-full-width="true"><thead><tr><th width="320.5">Subject of Onchain Voting Proposal</th><th>Phase 1 </th><th>Phase 2</th><th>Phase 3</th></tr></thead><tbody><tr><td>Software Changes and Upgrades</td><td>Foundation</td><td>Security Council, Foundation</td><td>Venn DAO</td></tr><tr><td>Emergency Fixes</td><td>Foundation</td><td>Security Council, Foundation</td><td>Security Council</td></tr><tr><td>Non-Emergency Fixes</td><td>Foundation</td><td>Security Council, Foundation</td><td>Security Council, Venn DAO</td></tr><tr><td>Treasury</td><td>Foundation</td><td>Foundation</td><td>Foundation, Venn DAO</td></tr><tr><td>Dispute Resolution</td><td>Foundation</td><td>Security Council</td><td>Security Council</td></tr><tr><td>Fees</td><td>Foundation</td><td>Security Council, Foundation</td><td>Venn DAO</td></tr><tr><td>Rewards</td><td>Foundation</td><td>Security Council, Foundation</td><td>Venn DAO</td></tr><tr><td>Slashing</td><td>Foundation</td><td>Security Council, Foundation</td><td>Security Council</td></tr><tr><td>Funding</td><td>Foundation</td><td>Foundation</td><td>Venn DAO</td></tr></tbody></table>

### Proposal Subject Definition:

1. **Software Changes and Upgrades:** Involves implementing updates and improvements to the network's software.
2. **Emergency Fixes:** Actions to immediately address and rectify critical vulnerabilities or threats.
3. **Non-emergency fixes:** Routine maintenance and minor upgrades to ensure the network runs smoothly.
4. **Treasury:** Management of the network's funds and financial resources.
5. **Dispute Resolution:** Handling conflicts and issues that arise within the network.
6. **Fees:** Determining and collecting fees from network participants.
7. **Rewards:** Distribution of incentives to participants who contribute positively to the network.
8. **Slashing:** Penalties imposed on participants who act maliciously or negligently.
9. **Funding:** Allocation of financial resources for various projects and operations within the network.

***

## Next Steps

As we progress towards full decentralization and permissionless state, our next steps involve detailing the on-chain governance mechanisms. We will publish the on-chain constitution, which will outline the rules and principles governing the Venn Security Network. Additionally, we will publish the quorum requirements for each proposal type, clearly defining the proposal processes.


# Consensus Model

## Introduction to the Venn Consensus Model

The Venn Consensus Model is a fundamental component of the Venn Security Network, designed to ensure secure and efficient transaction validation. This model is essential for maintaining network integrity and achieving agreement on transaction legitimacy among distributed participants.

***

## **The Need for a Consensus Mechanism**

* Achieving consensus is crucial for maintaining the network's security, reliability, and decentralized nature. It ensures that all participants have a consistent view of the blockchain and agree on the secure state of transactions.
* The consensus algorithm helps resolve intersubjective decision&#x73;**.** Intersubjective decisions require broad-based agreement among participants, which is essential for the network's integrity. Security exploits on the blockchain are also intersubjective, as recognizing and responding to them depends on shared belief and understanding among participants. The consensus mechanism enables this collective judgment, ensuring the network can identify and mitigate threats.
* Leverage Diverse Security Opinions and Methods: The Venn Consensus Model allows for incorporating diverse security methods and opinions from different participants. By enabling multiple security perspectives, the consensus mechanism ensures that a broader range of potential threats is considered, reducing the likelihood of vulnerabilities being overlooked. This diversity in security approaches enhances the network's resilience and adaptability to emerging attack vectors.
* Security Concerns: Assuming all node operators act honestly in a high-stakes security environment is inherently risky. A consensus mechanism addresses this by enforcing collective validation and decision-making, reducing the likelihood of dishonest behavior and enhancing overall network security.
* Even well-intentioned nodes can harm the network if they engage in blind voting to maximize rewards without properly validating transactions. This issue becomes particularly problematic in a permissionless stage where economic incentives heavily influence behavior.
* The potential economic value of a breach can be substantial, making it crucial to implement a robust consensus mechanism. This mechanism ensures that securing the network remains economically advantageous and prevents potential cheating by making dishonest actions unprofitable.

***

## Key Components

1. **Validation Process**
   * Node Operators: All node operators participate in validating transactions and maintaining the network infrastructure.
   * Voting: Transactions are validated through a voting process in which node operators vote on their legitimacy.
   * Consensus Algorithm: Venn's consensus algorithm aggregates votes and determines whether the transaction will be reverted or passed, making the final decision on transaction validity.
2. **Proof of Stake (PoS)**
   * Staking Requirements: Validators must stake tokens as collateral, incentivizing honest behavior and penalizing misconduct.
   * Weighted Voting Powe&#x72;**:** The amount of stake a validator holds influences their voting power, giving more weight to those with higher stakes. This also includes weighted voting power for validators with native Venn staking, enhancing their influence within the network.
3. **Correlated Agreement (CA) Model**
   * The CA model ensures validators' decisions are consistent with the overall network by analyzing the correlation between different validators' reports. This helps to detect and prevent collusion or coordinated attacks.
   * Validators’ decisions are cross-checked for consistency with others. High agreement among validators is required to finalize decisions, ensuring the integrity and reliability of the consensus process.
4. **Lazy Node Detection**
   * Venn employs a 'BOMB' mechanism similar to proofs of custody, where bomb transactions are sent in random time intervals to test node availability and security performance. This ensures nodes meet the expected Service Level Agreements (SLA).
   * Bomb transactions randomly test nodes, requiring them to prove their activity and responsiveness. Failure to respond appropriately results in penalties, incentivizing consistent performance.
5. **Governance and Oversight**
   * Security Council: Oversees the consensus process and resolves disputes related to validation and slashing events.
   * Community Participation encourages active participation from the community through staking, voting, and governance proposals.

***

## Transaction Outcomes in the Venn Consensus Model

Each transaction in the Venn Security Network can result in one of four possible outcomes, depending on how validators vote and the transaction's actual security status:

1. **Secure Transaction, Voted Secure**:\
   A legitimate transaction that is correctly identified as secure by the validators.
2. **Secure Transaction, Voted Not Secure (False Positive)**:\
   A legitimate transaction is incorrectly flagged as malicious by the validators. This is known as a **false positive**.
3. **Not Secure Transaction, Voted Not Secure**:\
   The validators correctly flag a malicious transaction as a threat and block it.
4. **Not Secure Transaction, Voted Secure (False Negative)**:\
   A malicious transaction is incorrectly voted secure by the validators.&#x20;

{% embed url="<https://link.excalidraw.com/readonly/3YSSQqC1xOuRSO3FcQqf?darkMode=true>" %}

***

## **Exception for Subnet** Consensus **Mode**

In Subnet Mode, a protocol can deploy Venn while delegating transaction validation and security measures to a selected subset of node operators. These nodes operate within a defined subnet, maintaining collective validation while adhering to the protocol's specific security policies. Each node in the subnet contributes to the consensus, sharing voting power rather than concentrating it on a single node. This approach enables a decentralized yet controlled validation, balancing flexibility and protocol-specific customization while maintaining the security and resilience of a broader network consensus.

## Exception for Standalone Consensus Mode&#x20;

A unique validation process is implemented in scenarios where a protocol deploys Venn and opts for **Standalone Mode**. Here, a single node operator is designated to handle all transaction validation and security measures. This node possesses 100% of the voting power, making it the sole authority in decision-making. This centralized approach allows for tailored and protocol-specific security mechanisms, ensuring that the chosen node can apply specialized measures to meet its custom requirements and security standards. This exception provides flexibility for protocols needing a more controlled and customized security environment.


# Economics

**Disclaimer**: The information provided on this page regarding Venn's economic model is for informational purposes only and is subject to change or updates as the network evolves. Any details about rewards or fees may be revised to reflect improvements, regulatory developments, or changes in strategy.

## *<mark style="color:yellow;">**Missing parts:**</mark>*

*<mark style="color:yellow;">\*add a part about the security fee itself</mark>*

*<mark style="color:yellow;">\*add subsidy for operators (rewards)</mark>*

*<mark style="color:yellow;">\*add payments for users (how it works)</mark>*

*<mark style="color:yellow;">\*add subsidy by protocols to users (how it works)</mark>*

*<mark style="color:yellow;">\*add</mark>* <mark style="color:yellow;"></mark><mark style="color:yellow;">Priority fee</mark>

## **Introduction to Venn** Economics

The Venn Security Network's economic framework ensures sustainability and growth while leveraging Eigen's crypto-economic risk models, ensuring the cost of corruption (CoC) remains prohibitively high. This section outlines the key components of Venn's economic models, including fee collection, reward distribution, slashing mechanisms, staking, and consensus.

***

## **Fee Collection and** Rewards Allocation&#x20;

The Venn Security Network employs a comprehensive fee collection mechanism to generate revenue, ensure the sustainability of network operations, and incentivize network participants. Fees are collected from network participants for various services, such as secure transaction validation and security services.

{% embed url="<https://link.excalidraw.com/readonly/bIvpNKBlyhwKdzV1Efer?darkMode=true>" fullWidth="true" %}

**Purpose**

Generate revenue to sustain network operations, fund ongoing development, and provide incentives for active network participation.

### **Fee Mechanism**

* Fees are collected through smart contracts for specific network services, including transaction validation and security features.
* Transaction fees are incurred either by the protocols' end users or by the protocols themselves if they choose to subsidize these fees for their ecosystem end users.
* Service fees are applied for additional services like custom security checks.

### Rewards[^1] Allocation

1. **Venn Default Network Mode**

In Venn Default Network Mode, all network operators validate transactions and vote on their legitimacy. The final decision is made using Venn’s consensus algorithm, ensuring a robust and decentralized validation process.

* **Infrastructure Node Operators:** x% of the fees are allocated to operators who maintain the network infrastructure and validate transactions.
* **Security Node Operators:** x% of the fees go to operators responsible for validating transactions using their unique and proprietary security methods.
* **Venn Foundation:** x% is allocated to the Venn Foundation for ongoing development and administrative expenses.
* **Security Council:** x% is directed to the Security Council to handle disputes and oversee network security.
* **Stakers:** x% is distributed to stakers who support the network's integrity through staking.

2. **Standalone Mode (priority fee)**

In Standalone Mode, an operator serves customers that connect exclusively and directly to their node end-point, giving the selected operator 100% power in the consensus mechanism. This mode is ideal for security operators with unique, custom, protocol-specific security mechanisms.

* The single Operator: x% fees are allocated to the single operator managing the transaction validation and security.
* **Infrastructure Node Operators:** x% of the fees are allocated to operators who maintain the network infrastructure and validate transactions.
* **Security Node Operators:** x% of the fees go to operators responsible for validating transactions using their unique and proprietary security methods.
* **Venn Foundation:** x% is allocated to the Venn Foundation for ongoing development and administrative expenses.
* **Security Council:** x% is directed to the Security Council to handle disputes and oversee network security.
* **Stakers:** x% is distributed to stakers who support the network's integrity through staking.

***

## **Slashing**

Slashing mechanisms penalize malicious or negligent behavior to maintain network integrity and security. Participants who act against the network's best interests, such as validating malicious transactions, face slashing penalties that reduce their staked tokens. Slashing addresses false positives, false negatives, severe malicious activity, uptime, and performance issues. Slashing is enforced automatically through smart contracts, ensuring fairness and transparency. The Security Council oversees disputes related to slashing events, providing an additional layer of scrutiny and resolution.

### **Slashing Conditions and Penalties:**

***

## **Staking**

The Venn Security Network incorporates staking and restaking (native and non-native) mechanisms to enhance economic security, incentivize participation, and ensure robust network performance. These mechanisms are based on EigenLayer frameworks and stack.

### **Staking**

**Purpose:**

* Staking allows participants to lock up their tokens to support network operations and security. In return, stakers earn rewards.

**Mechanism:**

* Participants stake their tokens through smart contracts, which enable them to support the Venn network, which will be distributed across the entire Venn network of operators.
* Stakers can choose to stake either in native tokens or ETH. Native staking earns bosted rewards and yields.
* Staking can be locked in intervals of 7 days, 14 days, 1 month, 3 months, 6 months, 12 months, and 24 months, with a longer time period yielding higher rewards.

**Rewards:**

* Rewards are distributed proportionally based on the amount and duration of the stake.

### **Delegation**

* Participants can delegate their restaked tokens to operators within the network, who are responsible for validating transactions and maintaining network integrity.
* Delegation involves selecting an operator through the Venn interface and confirming the transaction in a Web3 wallet.

### **Timelock Period of 7 Days**

* Restaked tokens are subject to a timelock period to enhance security. For example, LSTs and native staked tokens may have a withdrawal delay to ensure the integrity of the network during periods of vulnerability or anomalous behavior.

***

####

[^1]:


# Tokenomics

## Supply Details

| Property           | Details                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| Token              | `LAVA`                                                                                                             |
| Token supply       | `1,000,000,000 LAVA`                                                                                               |
| Deflation schedule | See the section below on.[“Lava Supply and Deflation”](https://docs.lavanet.xyz/supply#lava-supply-and-deflation-) |
|                    |                                                                                                                    |

### Supply and Deflation/Inflation  <a href="#lava-supply-and-deflation" id="lava-supply-and-deflation"></a>

### Distribution Breakdown <a href="#distribution-breakdown" id="distribution-breakdown"></a>

### Unlock Schedule <a href="#unlock-schedule" id="unlock-schedule"></a>

### Disclaimer <a href="#disclaimer" id="disclaimer"></a>


# Litepaper

The Venn Network Litepaper provides a concise overview of our modular security infrastructure.

***

{% embed url="<https://drive.google.com/file/d/1o9wr5DV2LFjuteep4H_rFTFXC8WzxQn5/view>" %}


# FAQ

<details>

<summary>How can the Venn Security Network protect my applications?</summary>

The Venn Security Network enhances application security by integrating off-chain intelligence with on-chain enforcement, facilitated by a decentralized consensus of security operators and teams. This network conducts thorough checks on transactions to validate their legitimacy and intent, applies dynamic and adaptive security methods, and utilizes a collaborative defense approach to detect and mitigate threats.&#x20;

</details>

<details>

<summary>Why should you use the Venn Security Network?</summary>

The increasing sophistication and frequency of security threats in the blockchain space require a new approach beyond traditional, isolated security measures. The Venn Security Network addresses these challenges by creating a unified, modular defense layer that combines the strengths of both on-chain and off-chain security mechanisms. This approach tackles existing security solutions' fragmentation and limited efficacy by enabling real-time, collaborative threat mitigation across a decentralized network. Utilizing the Venn Security Network allows for proactive defense against attacks tailored to the dynamic and evolving landscape of blockchain threats, ensuring comprehensive protection and maintaining the integrity and trust of your applications.

</details>

<details>

<summary>How is Venn's solution different from other security solutions?</summary>

Venn Security Network distinguishes itself from other security solutions by innovating on-chain and off-chain mechanisms within a decentralized framework.&#x20;

Here's how Venn's approach stands out:

1. **Decentralized Collaboration**: Unlike traditional security solutions that operate in silos, Venn leverages a network of node operators, security teams, and protocols, fostering a collaborative environment that enhances the overall security intelligence and response capabilities.
2. **Modular Security Layer**: Venn creates a modular defense layer that seamlessly combines the strengths of on-chain enforceability with the rich data and flexibility of off-chain processes. This holistic approach allows for more comprehensive threat mitigation and response than either method could achieve alone.
3. **Adaptive and Dynamic**: The network's security measures are not static; they evolve continuously as new threats are identified. This adaptability ensures security defenses remain effective against the latest vulnerabilities and attack vectors.
4. **Permissionless Participation**: Venn's decentralized nature means that any entity can contribute to and benefit from the network's security capabilities, democratizing security and enhancing coverage through widespread participation.
5. **Real-Time Defense**: By integrating real-time data from off-chain sources with on-chain actions, Venn provides immediate and proactive security responses that can prevent malicious transactions before they impact the network.
6. **Scalable and Affordable**: Venn's solution scales affordably with your application, ensuring that security meets your needs without becoming prohibitively expensive.
7. **Incentivized Security**: Venn uniquely incentivizes security for all participants, from application developers to node operators, security researchers, and stakers. Everyone involved is rewarded for their contributions, which enhances the robustness of the network and encourages ongoing engagement and improvement.

</details>

<details>

<summary>How can I integrate the Venn Network with my application or chain?</summary>

* **SDK Integration**: Start by integrating the Venn Network SDK into your application. This SDK facilitates the interaction between your application and the Venn Security Network, allowing you to send transaction data and receive security verifications.
* **Set Security Methods**: Define and set up the specific security methods you want to enforce through the Venn Network. This could include setting criteria for transaction validation, behavior monitoring, and other security checks.
* **Testing and Validation**: Thoroughly test the integration in a controlled environment to ensure that the security measures work as expected without disrupting your application’s performance.
* **Go Live**: Once testing is complete and you’re satisfied with the security integration, you can go live.&#x20;

</details>

<details>

<summary>Is the Venn Security Network decentralized?</summary>

Yes, the Venn Security Network is decentralized. It operates on a framework where multiple independent node operators, security teams, and other participants collaborate to provide security services. These operators reach a consensus on the legitimacy and security of transactions before processing. This decentralized structure distributes trust and ensures that no single point of failure can compromise the network's integrity, making it more resilient and robust.

</details>

<details>

<summary>Is the protection in Venn conducted on-chain or off-chain?</summary>

The protection in the Venn Security Network is conducted through a symbiosis of both on-chain and off-chain mechanisms. This hybrid approach leverages the strengths of each to provide comprehensive security. This integration of on-chain and off-chain mechanisms ensures robust, versatile, and effective security measures capable of addressing a wide range of threats while maintaining efficiency and scalability.

</details>

<details>

<summary>Can I customize my security requirements with Venn?</summary>

Yes, the Venn Security Network allows you to access various security methods and providers across the network. You can customize the security requirements to fit the specific needs of your application, leveraging diverse and specialized security services offered by various participants in the network. This flexibility enables you to tailor your security infrastructure to provide optimal protection.

</details>

<details>

<summary>What blockchain networks does Venn support?</summary>

The Venn Security Network is designed to be highly versatile and supports a wide range of networks, particularly those based on the Ethereum Virtual Machine (EVM).&#x20;

This includes:

1. **Ethereum Mainnet**
2. **Layer 2 Solutions**
3. **Sidechains**
4. **Rollups**
5. **Other EVM-Compatible Blockchains**

</details>

<details>

<summary>What are the costs using the Venn Security Network?</summary>

The costs associated with using the Venn Security Network include an added fee on top of the original transaction fees. This additional fee is distributed among network participants, compensating them for their roles in maintaining and enhancing the network's security. Venn supports different implementation and business models, ranging from subsidizing security by the chain for its DApps to staking mechanisms that allow participants to stake tokens in exchange for access to the network's services. This flexible approach enables various stakeholders to engage with the network in a way that aligns with their operational needs and economic models.

</details>

<details>

<summary>How can I become a part of the Venn Security Network?</summary>

To become a part of the Venn Security Network, you can follow these steps:

1. **Sign Up**: Begin by registering on the Venn Security Network Batch 2.&#x20;
2. **Integration and Setup**:
   * **Developers**: Integrate your applications with the Venn Security Network through the SDK.
   * **Node Operators**: Run a node and validate transactions within the network.
   * **Security Researchers**: Develop and implement your security logic, then add it to the network to enhance its collective security capabilities.
   * **Staking**: Contribute to network security and earn boosted yields.
3. **Active Participation**: Start actively participating in the network. This could involve validating transactions, providing security services, participating in governance through voting on network decisions, and contributing to the development of the network on GitHub.
4. **Continuous Learning and Adaptation**: Continuous learning and adaptation are crucial in actively contributing to and benefiting from the network.
5. **Join the Community**: Become involved in the Venn Security Network community. Follow the network’s updates, participate in discussions with other developers, and contribute to community-driven projects to stay engaged with the latest developments and opportunities.

By following these steps, you can become an integral part of the Venn Security Network, contributing to and benefiting from its decentralized security infrastructure.

</details>


# Community

At Venn Network, we believe in the transformative power of an engaged and diverse community to shape the future of blockchain security. We invite innovators, developers, and ecosystem partners to share ideas, collaborate on projects, and contribute to the advancement of decentralized security solutions.

Central to our mission is recognizing and appreciating meaningful contributions, reflecting our commitment to fostering an ecosystem where active participation drives innovation and progress.

By joining our community, you join a movement dedicated to collaborative efforts, paving the way for a more secure and resilient blockchain environment.

***

🌐 [**Venn Network Website**](https://www.venn.build/)

🐦 [**Official Twitter**](https://x.com/VennBuild)

💬 [**Official Discord**](https://discord.com/invite/venn)

👨‍💻 [**Official Telegram Developers Channel**](https://t.me/vennbuilders)

🔗 [**GitHub**](https://github.com/ironblocks)


# Audit Reports

At Venn, we prioritize the security and integrity of our protocol and ecosystem. In addition to conducting rigorous internal audits, we collaborate with trusted, industry-leading external partners to ensure our systems and infrastructure are secure. These comprehensive evaluations provide an additional layer of assurance, confirming that Venn meets the highest standards of security and reliability.

<table><thead><tr><th width="172.56640625">Auditor</th><th width="265.09375">Description</th><th width="152.91796875">Audit Date</th><th>Report</th></tr></thead><tbody><tr><td>Certora</td><td><ul><li>On-Chain Firewall v2</li><li>Venn Safe Guard</li></ul></td><td>Q1 2025</td><td><a href="https://storage.googleapis.com/www-venn-website/audits/Ironblocks%20-%20Firewall%20v2%20-%20Official%20Audit%20Report.pdf">Link</a></td></tr><tr><td>OpenZeppelin</td><td><ul><li>On-Chain Firewall</li></ul></td><td>Q1 2024</td><td><a href="https://blog.openzeppelin.com/ironblocks-onchain-firewall-audit">Link</a></td></tr></tbody></table>


# Detection Performance (internal)

Security Performance Metrics / Detection Performance Overview  / Accuracy & Trust

## Introduction&#x20;

This page outlines Venn’s detection accuracy, showing how often Venn accurately identifies malicious transactions and how rarely Venn mistakenly flags legitimate ones. These factors demonstrate Venn’s reliability in protecting your protocol, users, and assets.

***

## Key Metrics

* **True Positive: 60 out of 63** known hacks detected, **>\~95%**
* **False Negative: 3 out of 63** known hacks not detected, > **\~4%**
* **False Positive: \~0.08%** of \~3.1 million inspected transactions flagged

{% hint style="info" %}

* **False Negative: Malicious transactions that Venn failed to detect.**
* **False Positive: A legitimate transaction that the Venn system incorrectly flags as malicious.**
  {% endhint %}

***

## Methodology

**What We Did:**\
We forked Ethereum’s mainnet to create a controlled backtesting environment that mirrors **real-world conditions**. This allowed us to replay historical blocks and transactions as they originally occurred, ensuring our detection metrics reflect real on-chain activity.

**How We Did It:**

* **Timeframe & Blocks:**
  * The backtest spanned from **block 16,308,190** (Jan 1 2023 00:00 UTC) to **block 20,838,190** (Sep 26 2024 23:51 UTC).
  * This period lasts about 1.5 years and includes more than 4.5 million blocks.
* **Protocol & Assets:**
  * We included **64 protocols** representing a total of **280 assets**.
    * Of these, **63 protocols** had a verified exploit on record. One protocol was kept as a control group (with no known hack).
* **Transactions Inspected:**
  * We examined every transaction in which at least one of the selected protocol assets appeared in the call trace.
  * In total, this amounted to **over 3.1 million** transactions.

**Why We Did It:**\
By replaying a large, realistic slice of mainnet history and focusing on transactions tied to our selected protocols, we can accurately measure Venn’s ability to detect and block real exploits. This approach ensures our reported FP and FN numbers reliably reflect Venn’s performance in a production-like environment.

***

### Results & Interpretation

1. **High True Positive Rate (> 95%)**
   * Detecting 60 of the 63 hacks showcases strong coverage of attack patterns.
2. **Low False Positive Rate (< 0.08%)**
   * This low false positive rate means that legitimate transactions are rarely disrupted.
   * *Caveat:* Some of the flagged TXs may stem from exploits that have not been publicly disclosed.
3. **Impact**
   * Protocols: minimize disruption by producing a minimal amount of false alarms while maintaining robust protection against actual exploits.

***

## See Venn in Action

Check out the [**Hack Simulator**](https://explorer.venn.build/toolkit/time-travel/67508a394d66273f903a95e8)**,** where you can:

* Explore a list of historic hacks.
* Replay each hack under a Venn-enabled environment.
* Observe how Venn would have flagged and blocked the malicious transactions.
* Use the simulator to explore individual exploits and understand Venn.

***

{% hint style="info" %}
**Note:** All metrics on this page apply to Venn’s [**root network** ](/#venn-root-network)under the default security configuration. Subnets that utilize custom or specialized security models may exhibit different performance.
{% endhint %}


# Performance (internal)

## Introduction&#x20;

An overview of Venn’s **latency** characteristics, based on our latest benchmark data. This page outlines what we measure, how we measure it, and what to expect when using Venn in production.

***

## Latency Component Breakdown

1. **User ↔ Venn Node:**
   * Time for the user to send the transaction to the Venn node (Blockbeat).
2. **Fetching the Trace:**
   * Fetching the full transaction trace (internal calls, balances, logs) needed for inspection.
3. **Security Validation:**
   * Running the transaction through Venn detectors to decide if it’s malicious.
4. **Consensus (Operator Network):**
   * Back-and-forth communication among security operators to agree on the legitimacy of transactions.
5. **Signing:**
   * Operators sign off on the final decision and submit it on-chain.

***

## Benchmark Results

| Step                    | Duration (ms) in L1 | Duration (ms) in L2's |
| ----------------------- | ------------------- | --------------------- |
| **User ↔ Venn Node**    | 200                 | 100                   |
| **Fetching the Trace**  | 500                 | 500                   |
| **Security Validation** | 20                  | 20                    |
| **Consensus**           | 200                 | 100                   |
| **Signing**             | 50                  | 25                    |
| **Total**               | 500 ms              | 250 ms                |

{% hint style="info" %}
Note: Several of these steps (e.g., X and Y) occur in parallel, which helps reduce the overall end-to-end latency. Therefore, the total end-to-end latency is **not** the sum of each individual step.
{% endhint %}

***

## Factors Influencing Latency in Venn

* **Chain Type:**
  * L2 networks (e.g., Optimism, Arbitrum) typically finalize blocks more quickly than L1, which reduces end-to-end latency.
  * Native gas and block times on L1 (e.g., Ethereum Mainnet) create additional on-chain confirmation delays.
* **Number of Nodes (Operators):**
  * As you add more operator nodes, consensus can take longer (more validators contribute and validate).
* **Security Model:**
  * **Default Security (Root Network):** A standard configuration provides predictable performance.
  * **Custom Security (Subnets)**: The more complex security models you run, the longer the “Security Validation” component takes.
* **Transaction Complexity & Trace Size:**
  * Transactions involving large call trees or significant internal activity require more time to fetch and analyze the complete trace.
* **Network Conditions:**
  * High congestion or rapidly increasing gas fees can hinder on-chain finalization for the firewall transaction.
* **Geographic Location:**&#x20;
  * The distance between your client and the operator network affects latency.

***

By understanding and optimizing these factors—chain choice, operator setup, security model complexity, and resource allocation—you can guarantee that Venn’s latency stays minimal while still providing robust, real-time protection.


# Root vs Subnet (internal)

## Introduction&#x20;

Venn provides two security deployment options to fit different needs:

* **Root Network**: Venn's default, shared security layer- powerful, battle-tested, and ready for integration. Ideal for most protocols and developers in need of robust protection with a simple setup.
* **Subnets:** Customizable, dedicated security environments built on top of the Root Network. Best for unique implementations or specialized security requirements—allowing custom detectors, operator selection, and tailored fee structures.

***

## Core Differences: Root Network vs. Subnet

<table data-full-width="true"><thead><tr><th width="175.45703125">Aspect</th><th width="338.6171875">Root Network</th><th>Subnet</th></tr></thead><tbody><tr><td>Integration steps</td><td><p></p><ul><li><strong>Add Venn Modifiers to Your Smart Contracts</strong></li><li><strong>Deploy Updated Smart Contracts to Your Target Chain</strong></li><li><strong>Register Your Contracts with the Venn Root Network</strong></li></ul></td><td><p></p><ul><li><strong>Define Your Custom Security Requirements</strong></li><li><strong>Select Potential Operator Nodes to Fulfill Those Requirements</strong></li><li><strong>Add Venn Modifiers to Your Smart Contracts</strong></li><li><strong>Deploy Updated Smart Contracts to Your Target Chain</strong></li><li><strong>Register Your Contracts with Your Dedicated Subnet</strong></li></ul></td></tr><tr><td>Effort &#x26; Complexity</td><td><p><strong>Low Effort:</strong> </p><p></p><ul><li>Leverage Venn’s default detectors and SDK—no custom development.</li><li><strong>Quick Testing:</strong> Only basic integration tests (e.g., audit) are required.</li><li><strong>Minimal Coordination:</strong> Follow standard docs; no operator selection or custom security design.</li></ul></td><td><p><strong>High Effort:</strong></p><p></p><ul><li><strong>Custom Detector Development:</strong> Build, integrate, and thoroughly test the detection logic.</li><li><strong>Operator Selection:</strong> Identify and onboard a cohort of nodes aligned with your security needs.</li><li><strong>Use-Case Definition:</strong> Define precise threat models and validation rules.</li><li><strong>Comprehensive Testing:</strong> Perform backtesting and simulations to fine-tune performance.</li><li><strong>Extended Coordination:</strong> Deep collaboration between our security team, our engineering team, and chosen operators—more time-intensive and complex.</li></ul></td></tr><tr><td>Customization</td><td><p><strong>Limited:</strong></p><p></p><ul><li><strong>Protected Scope:</strong> Choose which smart contracts or specific functions to guard.</li><li><strong>Chain Selection:</strong> Pick from supported chains without modifying core detectors.</li><li><strong>Fee Model:</strong> Decide whether to subsidize security costs or pass fees to end users via a security surcharge.</li></ul></td><td><p><strong>High:</strong></p><p></p><ul><li><strong>Detectors &#x26; Rules:</strong> Create and configure entirely custom detection logic, thresholds, and policies.</li><li><strong>Operators:</strong>  select operator nodes specific to your subnet.</li><li><strong>Fee Structures:</strong> tailored to your economic and operational requirements.</li><li><strong>Environment Configuration:</strong> Customize every aspect of the security stack.</li></ul></td></tr><tr><td>SLA &#x26; Support</td><td>tbd</td><td>tbd</td></tr><tr><td>Pricing</td><td><ul><li><strong>Usage-Based Fees:</strong> Each protected transaction consumes a small on-chain fee (≈ $0.01) drawn from the pre-funded by the protocol security pool.</li><li><strong>Protocol-Subsidized:</strong> Protocol locks up (stakes) funds in the security pool; fees are deducted automatically.</li><li><strong>Billing Cycle:</strong> Security fees are collected weekly from the pool; any unspent funds can be unstaked and returned to the protocol.</li></ul></td><td><p></p><ul><li><strong>Custom Fee Models:</strong> Tailor your pricing to fit your needs—choose protocol-subsidized, user-paid, cross-chain aggregation fees, token swap levies, or other on-chain or off-chain payment structures.</li><li><strong>Onboarding &#x26; Setup Fees:</strong> Optional one-time fees for subnet configuration, operator provisioning, and custom SLA commitments.</li><li><strong>Billing Terms:</strong> Negotiable per integration—billing frequency, fee tiers, and staking requirements are defined in your subnet agreement.</li></ul></td></tr><tr><td>Use Cases</td><td><ul><li><p>DeFi Protocols</p><ul><li>AMMs</li><li>Lending &#x26; Borrowing</li><li>Derivatives</li><li>Yield Aggregators &#x26; Vaults</li><li>Stablecoin &#x26; Algorithmic Stablecoin</li><li>Launchpads &#x26; IDO Platforms</li><li>Insurance Protocols</li><li>Oracle Services/Price feeds</li><li>NFT / Marketplaces</li></ul></li></ul></td><td>Any use case can be potentially developed</td></tr></tbody></table>

{% hint style="info" %}
tbd
{% endhint %}

***

## Commonly used contracts suitable for Venn integration:

| Category                    | Contract Types                                                                                                         |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Token Standards**         | `ERC20` `SafeERC20` `ERC20Permit` `ERC20Capped`                                                                        |
| **Ownership & Access**      | `Ownable` `Pausable` `AccessControl TimelockController`                                                                |
| **Reentrancy & Safety**     | `ReentrancyGuard`                                                                                                      |
| **Upgradeable Proxies**     | `TransparentUpgradeableProxy` `UUPSProxy` `ProxyAdmin`                                                                 |
| **AMMs & Pools**            | `UniswapV2Pair` `UniswapV3Pool` `StableSwap CryptoPool`                                                                |
| **Staking & Rewards**       | `StakingRewards` `RewardPool`                                                                                          |
| **Governance**              | `GovernorAlpha` `GovernorBravo` `GovernorV2`                                                                           |
| **Snapshot & Voting**       | `Snapshot`                                                                                                             |
| **Vesting & Escrow**        | `TokenVesting` `TokenEscrow` `VestingRegistry`                                                                         |
| **Treasury & Fees**         | `FeeDistributor` `FeeCollector`                                                                                        |
| **Oracles & Data Feeds**    | Chainlink Aggregator Interfaces                                                                                        |
| **Batch Utilities**         | `Multicall` / `Multisend`                                                                                              |
| **NFT & Fractionalization** | <p><code>ERC-721</code> / <code>ERC-1155</code></p><p>Fractional Vaults (e.g. <code>ERC-4626</code> wrapping NFTs)</p> |
| **Cross-Chain Bridges**     | <p>Bridge Routers (e.g., Axelar, Hop) </p><p>Messaging & Relayer contracts</p>                                         |

{% hint style="info" %}
**Note:** You don’t need to use the exact OpenZeppelin contracts listed above—any version or fork of these patterns (or your own custom implementations) can also be secured by Venn. These examples simply illustrate common contract types and architectures found in DeFi.
{% endhint %}

***

## When to recommend Root Network and when a subnet

#### Root Network

* **Default Starting Point:** Almost every new integration should begin with the Root Network. It delivers robust, battle-tested security with minimal setup—ideal for most protocols and developers.
* **Rapid Time-to-Market**: If you need to go live quickly (within weeks), the standard configuration provides the fastest path.
* **Standard Threat Profiles:** For protocols whose security needs align with Venn’s core security logic, Root provides immediate value.

#### Subnet

* **Fallback for Specialized Needs:** If a prospect cannot—or chooses not to—move forward on the Root Network, then explore a Subnet.
* **Performance-Sensitive Integrations:** When latency or throughput demands exceed what Root’s shared operator network can guarantee, a dedicated Subnet can be tuned for low latency.
* **Custom Security Models:** If a protocol requires detectors or rules beyond Root’s standard set, a Subnet enables the implementation of those requirements.

{% hint style="info" %}
In practice, always lead with the Root Network. Reserve Subnets for advanced use cases where Root’s defaults won’t meet a client’s specialized performance or security needs.
{% endhint %}


# Addresses


# Points Campaign

## Overview

Venn's Points Program is designed to incentivize key participants within our ecosystem, primarily focusing on <mark style="color:purple;">`developers`</mark> at this campaign. This campaign offers points for specific actions and milestones to encourage developers to engage with Venn security frameworks, particularly the Venn Firewall.

## How to earn points:

The Points Program offers a variety of quests, each designed to engage you in different aspects of the Venn ecosystem. Whether you're a developer, contributor, or participant, you can earn points by completing these quests. Each quest is independent, meaning you can choose the ones that best align with your interests and strengths. Every quest comes with its own set of rewards, reflecting the value of the contribution to the Venn ecosystem.<br>

## List of quests&#x20;

{% hint style="info" %}
**Join the Venn Points Discord Server.**&#x20;
{% endhint %}

{% hint style="info" %}
**Star Venn GitHub Repository.**
{% endhint %}

{% hint style="info" %}
**Submit a Firewall Pull Request (PR).**
{% endhint %}

{% hint style="info" %}
**Deploy Firewall Smart Contract on Testnet.**
{% endhint %}

{% hint style="info" %}
**Deploy Firewall Smart Contract on Mainet.**
{% endhint %}

{% hint style="info" %}
**50 Firewall Tx on Mainet.**
{% endhint %}

{% hint style="info" %}
**100 Firewall Tx on Mainet.**
{% endhint %}

{% hint style="info" %}
**500 Firewall Tx on Mainet.**
{% endhint %}

{% hint style="info" %}
**1000+ Firewall Tx on Mainet.**
{% endhint %}

## **How to Get Started**

1. **Sign Up:** Connect your GitHub account and wallet to our points [platform](https://www.venn.build/).
2. **Read and Learn:** Explore each quest in the 'Quest Guide' to understand the requirements, rewards, and how you can maximize your points.
3. **Start Earning:** Engage with the outlined activities to begin earning points.
4. **Track Progress:** Monitor your points and rankings via the Personal Points Dashboard.

## **What do points represent?**

Points provide a quantitative answer to the question of how much a user has contributed to the success of the Venn ecosystem.

## FAQ

<details>

<summary>What are Points?</summary>

Points are a reward system within the Venn ecosystem designed to incentivize and recognize contributions. You earn points by participating in various quests.

</details>

<details>

<summary>What do Points Represent?</summary>

Points represent your level of engagement and contribution to the Venn ecosystem. They quantify your involvement and reward you for your efforts.<br>

</details>

<details>

<summary>Where Can I See My Points?</summary>

You can track your points and view your rankings on the Points Dashboard, accessible through the Points Dashboard.<br>

</details>

<details>

<summary>How Are Points Calculated?</summary>

Points are calculated based on specific quests. Each activity has its own point value, and points are awarded accordingly. you can see the exact details in rewards page ->

</details>

<details>

<summary>What is the Referral Program?</summary>

The referral program allows you to earn extra points by inviting others to join the Venn ecosystem. For every person you refer who participates in the program, you receive a percentage of the points they earn.

</details>

<details>

<summary>How Do I Participate in Quests?</summary>

Quests are individual challenges or tasks you can complete to earn points. Each quest is independent. Detailed instructions for each quest can be found in the {Quest Guide}.<br>

</details>


# Notes

## **Voting Power**

### The voting power of each validator is calculated using the following formula:

$$
\text{Voting Power of Validator } i = \frac{\text{Staked Tokens of Validator } i}{\sum\_{j=1}^{N} \text{Staked Tokens of All Validators}}
$$

Where:

* (i) represents a specific validator.
* (N) is the total number of validators.
* The sum in the denominator ensures that the voting power is normalized across all validators, and the sum of all voting power equals 1 (or 100%).

## **Transaction Validation Threshold**

### **Blocking Malicious Transactions**:

For a transaction to be flagged and blocked, at least 66% of the voting power must agree that it is malicious.

* Block Transaction 𝑇𝑥 if:

$$
\sum\_{i=1}^{K} Voting Power of Validators Flagging T
x
​
 as Malicious ≥ 66%
$$

Where:

* i represents a specific validator.
* K is the set of validators that flagged the transaction as malicious.
* The summation represents the voting power of validators who believe the transaction is malicious.

### **Approving Transactions**

If the consensus to flag a transaction as malicious **does not** reach 66%, the transaction will be **approved by default**.

Approve Transaction 𝑇𝑥 if:

$$
\sum\_{i=1}^{K} Voting Power of Validators Flagging T
x
​
 as Malicious < 66%
$$

In this case, if the voting power flagging the transaction as malicious is below 66%, the transaction is **approved** by default.

### Summary

* **Weighted Influence**: Validators’ voting power is proportional to their stake, meaning those more at risk significantly influence the decision-making process. This creates a strong incentive for validators to act in the network’s best interest.
* **Broad-based agreement**: The 66% threshold ensures that decisions on transaction validity reflect broad-based agreement among validators. This collective judgment makes it difficult for any single validator or small group to exert undue influence over the consensus, reinforcing the network's decentralized nature.
* **Penalization of Malicious Actors**: Validators who attempt to approve or push through malicious transactions risk losing their staked assets through slashing mechanisms.