Custom Threat Detection

Overview

The process of building custom detection models involves the following steps:

1. Write a web-service that conforms to the External Detector API specification listed below

2. Add your web-service as a new detector in your Venn node client configuration

3. When the Venn node client receives a request to inspect a transaction, it will now use your configured web-service for the detection stage

4. Your web-service responds with the detection results

5. That's it!

You can use the boilerplate template to build custom detection solutions on the Venn Network.

---

External Detector API

v0.8 [BETA]

Inspection Request

POST /detect

A web-service over HTTP that is used by Venn node clients to inspect transactions

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description	Required
Id	string	The unique identifier for the request.	Yes
ChainId	int64	The identifier of the Ethereum chain.	Yes
Hash	string	The hash of the transaction. (In Signer mode, it's the Hash of the transaction payload)	Yes
ProtocolName	string	The name of the protocol associated with the transaction.	Yes
ProtocolAddress	string	The address of the protocol associated with the transaction.	Yes
Trace	JSON	The complete transaction trace data. See: https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers#call-tracer	Yes
AdditionalData	JSON	Additional data associated with the transaction.	No

---

Inspection Response

Your web-service should always respond with a 200 OK HTTP response code.

Errors should be indicated using the boolean Error field, with a helpful error message in the Message field

Field	Type	Description	Required
RequestId	string	The unique identifier for the corresponding request.	Yes
ChainId	int64	The identifier of the Ethereum chain.	Yes
Detected	bool	Indicates whether the transaction is malicious	Yes
Error	bool	Indicates whether an error occurred during processing.	No
Message	string	An optional message providing additional information.	No
ProtocolAddress	string	The address of the protocol associated with the transaction.	No
ProtocolName	string	The name of the protocol associated with the transaction.	No
AdditionalData	JSON	Additional data associated with the response.	No

---

Payload Examples

Request

{
  "id": "4d76926d-f62a-4d96-a8a7-a804fd092406",
  "chainId": 11155111,
  "hash": "0x60944fbe16e7985bf8229959bf23466f16f6a8315377dd18777e669cc59576d0",
  "protocolName": "protocol2",
  "protocolAddress": "0x50ea82a38ce8d86fd2be8a922f3764e0d7b3a3c8",
  "trace": {
    "from": "0xf092dad59019613109cb8cec9547b2aee3bb6f28",
    "gas": "0x23c34600",
    "gasUsed": "0xe793",
    "to": "0x3f7dc4e25873aef3b66f72fca231551ce419e16a",
    "input": "0x3ff4115a000000000000000000000000023bd4e8d908a5a998a0e3d2772ee63b5806aa8d",
    "output": "0x08c379a000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000026417070726f76656443616c6c73506f6c6963793a2063616c6c2068617368657320656d7074790000000000000000000000000000000000000000000000000000",
    "calls": [
      {
        "from": "0x3f7dc4e25873aef3b66f72fca231551ce419e16a",
        "gas": "0x2333c0fd",
        "gasUsed": "0x6d67",
        "to": "0x023bd4e8d908a5a998a0e3d2772ee63b5806aa8d",
        "input": "0xd0e30db0",
        "output": "0x08c379a000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000026417070726f76656443616c6c73506f6c6963793a2063616c6c2068617368657320656d7074790000000000000000000000000000000000000000000000000000",
        "calls": [
          {
            "from": "0x023bd4e8d908a5a998a0e3d2772ee63b5806aa8d",
            "gas": "0x22a6dd1f",
            "gasUsed": "0x5803",
            "to": "0x50ea82a38ce8d86fd2be8a922f3764e0d7b3a3c8",
            "input": "0x6fe1967c0000000000000000000000003f7dc4e25873aef3b66f72fca231551ce419e16a00000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000b5e620f480000000000000000000000000000000000000000000000000000000000000000004d0e30db000000000000000000000000000000000000000000000000000000000",
            "output": "0x08c379a000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000026417070726f76656443616c6c73506f6c6963793a2063616c6c2068617368657320656d7074790000000000000000000000000000000000000000000000000000",
            "calls": [
              {
                "from": "0x50ea82a38ce8d86fd2be8a922f3764e0d7b3a3c8",
                "gas": "0x221c0f9c",
                "gasUsed": "0x24f4",
                "to": "0xfa54c0997a17dba48e5bec44e7d1e610f85d9756",
                "input": "0xd9739cda000000000000000000000000023bd4e8d908a5a998a0e3d2772ee63b5806aa8d0000000000000000000000003f7dc4e25873aef3b66f72fca231551ce419e16a00000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000b5e620f480000000000000000000000000000000000000000000000000000000000000000004d0e30db000000000000000000000000000000000000000000000000000000000",
                "output": "0x08c379a000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000026417070726f76656443616c6c73506f6c6963793a2063616c6c2068617368657320656d7074790000000000000000000000000000000000000000000000000000",
                "value": "0x0",
                "type": "CALL",
                "error": "execution reverted",
                "revertReason": "ApprovedCallsPolicy: call hashes empty",
                "_callId": 3
              }
            ],
            "value": "0x0",
            "type": "CALL",
            "error": "execution reverted",
            "revertReason": "ApprovedCallsPolicy: call hashes empty",
            "_callId": 2
          }
        ],
        "value": "0xb5e620f48000",
        "type": "CALL",
        "error": "execution reverted",
        "revertReason": "ApprovedCallsPolicy: call hashes empty",
        "_callId": 1
      }
    ],
    "value": "0x16345785d8a0000",
    "type": "CALL",
    "error": "execution reverted",
    "revertReason": "ApprovedCallsPolicy: call hashes empty",
    "_callId": 0,
    "pre": {
      "0xf092dad59019613109cb8cec9547b2aee3bb6f28": {
        "balance": "0x574bc5cf4efe0fe",
        "nonce": 85
      }
    },
    "post": {
      "0xf092dad59019613109cb8cec9547b2aee3bb6f28": {
        "nonce": 86
      }
    }
  },
  "additionalData": {
    "rpc_url": "https://solemn-young-telescope.ethereum-sepolia.quiknode.pro/.../"
  }
}

Response

{
  "requestId": "007692d0-87a1-42fa-92b8-954846c4b44e",
  "chainId": 11155111,
  "detected": true,
  "protocolAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "protocolName": "SomeProtocol",
  "additionalData": {
    "key1": "value1",
    "key2": "value2"
  }
}