👋 Hello Venn

Welcome, fellow builder!
This repository is your quick start guide to Venn intergration for smart contracts and dApps. Think of it as your "Hello World" for Venn, designed to get you up and running in 10 minutes or less. 🏆

By the end of this tutorial, you’ll have a secure, Venn-enabled Safe Vault demo dApp.

Table of Contents

1. Your Demo dApp - A Safe Vault
2. Prerequisits
3. Step 0: Setup
4. Step 1: Add Venn To Your Smart Contracts
5. Step 2: Enable Venn
6. Step 3: Add Venn SDK To Your Frontend
7. Bonus Round

Your Demo dApp - A Safe Vault

The Safe Vault is a simple smart contract designed to help you get hands-on with Venn’s security features. Learn the basics without unnecessary complexity.

The Safe Vault contract SafeVault.sol has the following interface:

• deposits a mapping between a user's address and how much ETH they have
  
  

• deposit() a method for users to deposit ETH to the vault
  
  

• withdraw() a method for users to withdraw previously deposited ETH
  
  

Prerequisits

• A wallet with some at Holesky ETH in it, if you need testnet tokens, you can get them from a faucet such as Google Faucet

Step 0 / Setup

Before we dive into integrating Venn, let’s ensure the demo dApp is correctly set up and everything works as expected.

Follow these steps to get started:

1. Clone the Repo 🖥️

   git clone https://github.com/ironblocks/hello-venn.git
   cd hello-venn

   
   

2. Install Dependencies 📦

   npm ci

   
   

3. Setup Environment Variables 🔑
   Copy the .env.example file to .env and set the values:

   cp .env.example .env

   Make sure to set the following environment variables:

   • PRIVATE_KEY the key you will use for deploying this contract
     
     

   • HOLESKY_RPC_URL the RPC URL to connect to Holesky
     
     

   • VENN_PRIVATE_KEY used by the venn-cli to send Venn setup transactions. Usually, this would be the same as your PRIVATE_KEY
     
     
     

4. Run Tests 🧪

   npm test

   All tests pass, and we can continue to the next step.
   
   

Step 1 / Add Venn To Your Smart Contracts

Now that your demo dApp is set up, it’s time to make your smart contracts Venn Ready. In this step, we’ll integrate Venn’s security framework into the Safe Vault contract using the venn-cli.

This integration will:

• Add Venn-Modifiers to your contract.
• Prepare your contract to use Venn’s security infrastructure without changing its existing functionality.
• Enable Venn, and move from Venn Ready to Venn Enabled in Step 2 below.

1. Install Venn CLI 📦

   npm i -g @vennbuild/cli

   
   

2. Run the CLI on our contracts 🛠️

   venn fw integ -d contracts

   Note: On the first run, this will also install the @ironblocks/firewall-consumer SDK package

   
   

3. Review Changes to SafeVault.sol 🔎

   • An import for VennFirewallConsumer was added
   • The contract now inherits the VennFirewallConsumer
   • External methods are now firewallProtected
   
   

4. Verify Tests Still Pass 🧪

   npm test

   
   

5. Deploy 🚀

   npm run step:1:deploy

   
   

6. End 2 End Tests ☘️

   npm run step:1:deposit
   npm run step:1:withdraw

   Now that our contracts are Venn Ready, let's move on to making them Venn Enabled.

   
   

Step 2 / Enable Venn

With your smart contracts now Venn Ready, it’s time to activate Venn’s security features. Using the venn-cli, we’ll enable real-time protection, ensuring your contracts are safeguarded against malicious transactions.

1. Enable Venn 🛡️

   venn enable --network holesky

   Our SafeVault is now protected by Venn.

   
   

2. Venn Policy Address 📌

   The CLI also prints out the address of our new Venn Policy
   We'll need it in the next step, so go ahead and copy it into the venn.config.json file as follows:

   {
      "networks": {
         "holesky": {
               "contracts": {
                  "SafeVault": "..."
               },
               "policyAddress": "PASTE YOUR POLICY ADDRESS HERE"
         }
      }
   }

   
   

3. But Now Everything's Broken 😱

   If we now try to deposit or withdraw, our transactions will fail

   npm run step:2:deposit
   npm run step:2:withdraw

   This is because Venn only allows approved transactions to go through.
   So, how do we get our transactions approved by Venn?
   

   TIP: See these Firewall Reverted transactions on the Venn Explorer

   
   

Step 3 / Add Venn SDK To Your Frontend

To complete your integration, we’ll use the Venn dApp SDK to ensure every transaction from your frontend is securely validated before being sent on-chain.

1. Install The SDK 📦

   npm i @vennbuild/venn-dapp-sdk

   
   

2. Review The SDK Code 🖥️

   For the purpose of this guide, we took the liberty of preparing all the code in advance, so you don't have to.
   
   

   Checkout the integration code in the file step-3/deposit.ts:

   const vennClient = new VennClient({
        vennURL: VENN_SIGNER_URL,
        vennPolicyAddress: VENN_POLICY_ADDRESS
   });
   
   ...
   
   const approvedTx = await vennClient.approve({
      from: owner.address,
      to: SAFE_VAULT_ADDRESS,
      value: hre.ethers.parseEther("0.0001").toString(),
      data: safeVault.interface.encodeFunctionData("deposit")
   });

   
   

3. Run Approved Transactions 📦

   With the Venn DApp SDK installed, our updated deposit and withdraw scripts are now working again:
   
   

   npm run step:3:deposit
   npm run step:3:withdraw

   
   

   TIP: See these transactions on the Venn Explorer

   
   

Bonus Round

• Checkout Venn Playground for a live version of the SafeVault Hello Venn DApp
  

• Use the Venn Explorer to ... well, explore :)