@vennbuild/venn-dapp-sdk

Venn DApp SDK

SDK for easy DApp integrations with Venn Security Network

👉 What is Venn?

Table of Contents

• 🚀 Quick Start
• 📦 Installation
• 📚 Usage
  • Approving Transactions
  • Venn Client
  • Security Nodes
  • Strict Mode
• ⚙️ Configuration
• 💬 Support & Documentation
• 📜 License

🚀 Quick Start

Follow these steps to protect your DApp with Venn:

1. Install the SDK in your project:

   npm i @vennbuild/venn-dapp-sdk

2. Instantiate a new VennClient:

   import { VennClient } from '@vennbuild/venn-dapp-sdk';
   
   const vennURL           = process.env.VENN_NODE_URL;
   const vennPolicyAddress = process.env.VENN_POLICY_ADDRESS;
   
   const vennClient = new VennClient({ vennURL, vennPolicyAddress });

3. Approve your users transactions with Venn:

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

4. Finally, send the approved transaction onchain as your DApp normally would

   const receipt = await wallet.sendTransaction(approvedTransaction);

📦 Installation

Prerequisites

• You have integrated the Firewall SDK into your smart contracts
• You have the address of your Venn Policy

Install

npm install @vennbuild/venn-dapp-sdk

📚 Usage

Use this SDK to easily integrate your DApp with Venn.
First, make sure you have integrated your smart contracts with the Firewall SDK, and that you have your Venn Policy address readily available.

Approving Transactions

Once your smart contracts protected by Venn, only approved transactions will be allowed to go through. Transactions that are not approved will be reverted onchain.

This SDK will ensure your DApp's Frontend approves transactions with Venn before sending them onchain.

Venn Client

The VennClient is your DApp's entry point for interacting with Venn.
It provides a simple transaction approval interface that seamlessly integrates with your existing DApp's code:

import { VennClient } from '@ironblocks/venn-dapp-sdk';

const vennURL           = process.env.VENN_NODE_URL;
const vennPolicyAddress = process.env.VENN_POLICY_ADDRESS;

const vennClient = new VennClient({ vennURL, vennPolicyAddress });
const approvedTx = await vennClient.approve({ from, to, data, value });

The approved transactions has the same to, from, and value, with an updated data field that now includes a secure signature that will allow the transaction to go through the onchain Firewall

console.log(approvedTx);

/**
 * {
 *      from: original from
 *      to: original to
 *      data: <SECURE SIGNATURE + ORIGINAL DATA> (hex string)
 *      value: original value
 * }

Security Nodes

Venn protects your protocol by leveraging collective intelligence of multiple security node operators, all at once, in real time.

When the VennClient approves a transaction, it takes the original user transaction (in the form of { from, to, data, value }) and sends it to any one of it's security nodes for inspection.

The security nodes propagate the transaction to all nodes on the network via P2P, and responds back with a signed transaction (in the form of { from, to, data, value }) that your DApp can now submit onchain.

Strict Mode

By default, the SDK runs with strict mode enabled.

Enabled

In strict mode, if an error occurs while trying to approve the transaction, or if the transaction was not approved by Venn - the SDK will throw an error.

Your DApp will need to handle this gracefully handle this error:

The signed transactions has the same to, from, and value, with an updated data field that now includes a secure signature that will allow the transaction to go through the onchain Firewall

import { errors } from '@ironblocks/venn-dapp-sdk'

try {
    const approvedTx = await vennClient.approve({
        from,
        to,
        data,
        value
    });
}
catch (e) {
    // handle errors and unapproved transactions
    //
    // for example, alert the user that the transaction did not pass security checks etc

    if (!(e instanceof Error)) return alert(e)

    switch(error.constructor) {
        case errors.InvalidInitParamsError:
            return alert(`Invalid params: ${error.message}`)
        case errors.ConnectionRefused:
            return alert(`Network error: ${error.message}`)
        case errors.TxRejectedError:
            return alert(`Venn Error: Tx Not Approved: ${error.message}`)
        default:
            return alert('Something wrong...')
    }
}

Disabled

When strict mode is disabled, the SDK will gracefully handle any errors internally - including ignoring unapproved transactions.

⚠️
IMPORTANT: While it may make sense for certain DApps to disable strict mode, we strongly encourage you to keep strict mode enabled

⚙️ Configuration

• vennURL: string
  the Venn security node to connect the client to

• vennPolicyAddress: string
  the address of your Venn Policy

• strict: boolean
  whether or not to enable strict mode (default: true)

💬 Support & Documentation

We're here to help.

• Join the discussion on Discord: Venn Discord

• Read the docs: Venn Documentation

📜 License

Venn DApp SDK is released under the MIT License.

This SDK demonstrates how to integrate DApps with Venn Network together with Ironblocks Firewall