Consul Smart Contract

Inspiration and Rationale

Historically, botnets such as Zeus, Cutwail, and Storm dominated the cybercrime landscape. They spread malware, executed spam campaigns, and harvested sensitive data from victims worldwide. Though their architectures varied, each demonstrated how large, remotely controlled networks of compromised machines could be orchestrated with remarkable efficiency. Yet, these successes were overshadowed by a critical weakness: all three relied on identifiable control points or exploitable vulnerabilities that allowed determined defenders to sabotage their operations.

• Zeus and Cutwail: Centralized command-and-control (C2) servers served as the backbone of these botnets. Once law enforcement or security researchers located and neutralized these central hubs, the botnets effectively ceased to function. Seizing servers, cutting off communication channels, or isolating key nodes were common strategies used by defenders to bring these networks down.

• Storm: A peer-to-peer (P2P) botnet that appeared highly resilient at first. It infected millions of computers worldwide, leveraging a decentralized structure that made takedown efforts more challenging. However, persistent security measures eventually crippled the network. Microsoft’s Malicious Software Removal Tool (MSRT) disinfected hundreds of thousands of PCs, and German researchers discovered flaws in Storm’s cryptography and network challenges. By mid-2008, Storm’s infection numbers plummeted, forcing the operators to abandon their operations and likely move on to other malicious networks.

These cases highlight a fundamental lesson: even the most formidable botnets can be weakened or dismantled by targeting their central points of failure or exploiting hidden technical vulnerabilities. The Consul smart contract draws inspiration from these historical precedents, using blockchain technology to remove the obvious Achilles’ heel of centralized servers and single points of compromise.

---

Overview

The Consul smart contract is designed to manage a decentralized network of Praetor nodes and their servers. Instead of central C2 servers or easily exploited vulnerabilities, Consul leverages blockchain’s distributed ledger technology to provide a stable, censorship-resistant, and tamper-evident foundation. This decentralized approach makes it significantly harder to dismantle or control, drawing from the lessons learned in the downfall of Zeus, Cutwail, and Storm.

The core idea: no single server shutdown or compromised node should cripple the entire network. Using a blockchain-based architecture, Consul aims to ensure that even if some nodes fail, the network’s command and control remain intact.

---

Censorship Resistance and Security

By utilizing blockchain technology, the Consul architecture ensures:

• Censorship Resistance: No single entity can simply "turn off" the network. Commands and management operations are recorded on a public, immutable ledger. This transparency and distributed storage prevent bad actors or authorities from easily dismantling the network by taking out a few servers.

• Increased Security Against Attacks: The immutable nature of blockchain records guarantees that command histories, node changes, and other essential operations cannot be surreptitiously altered or erased. The entire operational history is permanently inscribed on-chain, providing a reliable audit trail.

Historical botnets like Storm faced decisive blows through well-orchestrated cleanup campaigns—Microsoft’s MSRT removal efforts for Storm are a prime example. While such campaigns were highly effective for traditional botnets, the decentralized and tamper-resistant nature of a blockchain-based system raises the bar significantly, making large-scale, single-point interventions far more difficult.

---

Core Components

Praetor Management

Praetors represent worker nodes within the network. They are stored on-chain as structs holding essential details:

• Server IP address and port
• ENS (Ethereum Name Service) name
• Node IP address and port

Praetor Functions:

• Add a Praetor: Scale the network by introducing new nodes.
• Remove a Praetor: Cleanly excise compromised or no-longer-useful nodes.
• Deactivate a Praetor: Temporarily disable nodes without fully removing them, allowing flexible, on-chain maintenance strategies.

Command Management

The contract maintains a history of commands, ensuring every directive is transparent and auditable. The default command is REPORT.

Command Functions:

• Change the Current Command: Controllers can update the network’s active instructions.
• Get the Current Command: Quickly verify which directive the network is currently following.
• Access the Command History: Retrieve past commands by index, and determine the command history length for auditing and analysis.

This historical record ensures stakeholders can learn from previous directives, track suspicious activity, and adapt strategies accordingly—much like researchers studied and adapted to the evolving strategies of Storm, Zeus, and Cutwail operators.

Dictator Mode

"Dictator mode" acts as a fallback. If Praetor nodes are compromised, the owner can centralize control through the Consul contract. While less flexible and potentially more expensive in gas costs, this mode ensures control can be maintained during emergencies—akin to a last-resort defense mechanism.

Dictator Mode Functions:

• Toggle Dictator Mode: Enable or disable the fallback control mechanism.
• Check Dictator Mode State: Instantly see if dictator mode is active.
• Add Payloads: Insert target data (e.g., email addresses for spam, IP addresses for DDoS) directly into the blockchain.
• Remove Payloads: Eliminate payloads that are no longer required or considered risky.
• Get Payload by ID: Retrieve specifics on particular payloads for meticulous oversight.

Dictator mode serves as an insurance policy. It in effect uses the threat of a fork on the host blockchain as leverage against efforts to remove the dictator code or Consul contract. Unlike the permanent centralization found in traditional botnets, dictator mode is optional and can be engaged only under dire circumstances.

---

Access Control

Consul uses OpenZeppelin’s AccessControl to manage roles and permissions:

• Owner (OWNER_ROLE): Wields ultimate authority, can delegate powers, and manage Praetors. The owner can change who controls the contract to ensure continuity or hand off management if needed.
• Controller (CONTROLLER_ROLE): Manages commands and payloads but cannot alter ownership or directly manage Praetors. This structure resembles the layered defenses and access levels that defenders leveraged against Storm, Zeus, and Cutwail—maintaining strict separation of powers to prevent catastrophic misuse.

---

Conclusion

The Consul smart contract is the culmination of lessons learned from some of the most notorious botnets:

• Zeus and Cutwail revealed the danger of centralized servers—shutdown one node, and the entire network can fail.
• Storm showed that even P2P structures could be exploited if defenders applied continuous pressure, found cryptographic flaws, and relentlessly disinfected infected hosts.

Consul takes these insights to heart, leveraging blockchain technology to create a censorship-resistant, tamper-evident ecosystem that is inherently more difficult to dismantle. While Storm’s operators were forced to abandon their botnet due to persistent cleanup efforts, the aim here is to craft a system resistant to such overt takedowns, ensuring that no single lever—or single flaw—can bring the entire network to its knees.

This approach does not guarantee invincibility, but it significantly raises the bar. By distributing functionality and providing fallback mechanisms, Consul marks a new era in decentralized network management—one informed by the past but prepared for the future.

Coverage Report

Statements	Functions	Lines

Prerequisites

• Docker

PATH+=":./bin"    # use your sh files (which are located in bin/) directly from the root of the project

yarn install      # install deps
yarn run build    # install solc and other tools in the docker image

Don't forget to copy the .env.example file to a file named .env, and then edit it to fill in the details.

Running all the tests

yarn run test
yarn run test:trace       # shows logs + calls
yarn run test:fresh       # force compile and then run tests
yarn run test:coverage    # run tests with coverage reports

Formatters & Linters

You can use the below packages,

• Solhint
• ESLint
• Prettier
• CSpell
• ShellCheck

yarn run format
yarn run lint

Analyzers

You can use the below tools,

• Slither
• Mythril

yarn run analyze:static path/to/contract
yarn run analyze:security path/to/contract
yarn run analyze:all path/to/contract

Deploy Contract & Verification

To try out Etherscan verification, you first need to deploy a contract to an Ethereum network that's supported by Etherscan, such as Ropsten.

In this project, copy the .env.example file to a file named .env, and then edit it to fill in the details.

• Enter your Etherscan API key
• Ropsten node URL (eg from Alchemy)
• The private key of the account which will send the deployment transaction.

With a valid .env file in place, first deploy your contract:

yarn run deploy ropsten <CONTRACT_FILE_NAME>    # related to scripts/deploy/<CONTRACT_FILE_NAME>.ts
yarn run deploy:all ropsten                     # related to scripts/deploy.ts

Also, you can add contract(s) manually to your tenderly projects from the output. https://dashboard.tenderly.co/contract/<NETWORK_NAME>/<CONTRACT_ADDRESS>

And then verify it:

yarn run verify ropsten <DEPLOYED_CONTRACT_ADDRESS> "<CONSTRUCTOR_ARGUMENT(S)>"    # hardhat.config.ts to see all networks

Finder

yarn run finder --path contracts/Workshop.sol --name Workshop abi --colorify --compact --prettify    # find contract outputs of specific contract

yarn run finder --help    # see all supported outputs (abi, metadata, bytecode and more than 20+ outputs)

Miscellaneous

yarn run generate:docs    # generate docs according to the contracts/ folder

yarn run generate:flatten ./path/to/contract     # generate the flatten file (path must be "./" prefixed)
yarn run generate:abi ./path/to/contract         # generate the ABI file (path must be "./" prefixed)
yarn run generate:bin ./path/to/contract         # generate the binary in a hex (path must be "./" prefixed)
yarn run generate:metadata ./path/to/contract    # generate the metadata (path must be "./" prefixed)
yarn run generate:all-abi
yarn run generate:all-bin
yarn run generate:all-metadata

yarn run share    # share project folder with remix ide

Making encoded payloads

First, create a "Hello World" Python script file named hello_world.py:

Then, use the following Python code to convert the hello_world.py file into a hexadecimal string:

with open("hello_world.py", "rb") as file:
    content = file.read()
    hex_string = content.hex()

print(hex_string)

Run the Python script above, and it will output a hexadecimal string representing the contents of the hello_world.py file. Copy this hexadecimal string and use it as input for TypeScript.

Decoding payload

Replace the retrieved_payload variable with the actual payload data returned from the getPayload function:

def bytes_array_to_hex(byte_array):
    return ''.join(byte[2:] for byte in byte_array)

def hex_to_str(hex_string):
    return bytes.fromhex(hex_string).decode('utf-8')

retrieved_payload = ['0x70', '0x72', '0x69', '0x6e', '0x74', '0x28', '0x48', '0x65', '0x6c', '0x6c', '0x6f', '0x2c', '0x20', '0x57', '0x6f', '0x72', '0x6c', '0x64', '0x21', '0x29']  # Replace this with the output from getPayload

hex_string = bytes_array_to_hex(retrieved_payload)
decoded_string = hex_to_str(hex_string)

print(decoded_string)

Credit to https://github.com/emretepedev/solidity-hardhat-typescript-boilerplate for the template