How it works
TL;DR
The on-chain Firewall works by allowing protocols to specify a security parameter (number) that may not change by more than a given amount, in a given time window. Using the TVL as the security parameter would effectively enable protocols to track huge and sudden TVL declines, which are highly indicative of malicious activity, directly on-chain.
Parameter-Based System
The parameter-based design of the system is the cornerstone of the Firewall’s effective operation. This system allows any protocol to define a configuration for their Firewall.
The protocol can configure the Firewall with a threshold percentage (for the parameter), a block interval (time period), and a starting parameter. The parameter, can then be updated at any time. Whenever the current parameter changes by more than the set threshold, the Firewall gets triggered. Protocol’s may individualistically decide upon fitting protective measures that are initiated upon a Firewall trigger.
Parameter as a Tracking Tool
The security parameter (a number) serves as a tracking tool. In a simple implementation, this parameter could be the Total Value Locked (TVL) of a protocol. By using the TVL as the parameter, the system can monitor the volume of withdrawals from the protocol. This is particularly useful in preventing large, sudden withdrawals within a short time frame, which are often indicative of malicious activity or a potential hack. Most protocols experience a significant withdrawal within a single transaction when being hacked, and parameter-based Firewall systems can help prevent that from happening.
Configuration parameters in detail
The Firewall configuration can be set up by the protocol governance / owner, by defining a set of rules for the individual Firewall implementation. The combination of these rules allow for highly individualistic and dynamic Firewall implementations.
Defining configuration parameters
Start parameter: Is the starting security parameter for a given protocol’s security parameter.
Threshold percentage: Defines the maximum limit, which a parameter is allowed to change in a given time window.
Block interval: Defines the number of blocks (time window) within the parameter should not change by more than the threshold percentage.
Optional: The cooldown period : Defines the period of time a protocol must wait before they can change their security parameters again after the Firewall has been activated.
NOTE: If storing multiple security parameters, configuration has to be done for each security parameter separately.
Versatility and Composability
One of the key strengths of the parameter-based system is its high versatility and composability. Protocol’s can choose what they want to track and use to identify malicious activity. While TVL is a common choice for tracking large withdrawals, protocols are not limited to this. They could choose to track other parameters that are indicative of hacks, depending on their specific needs and circumstances. This allows for highly individualistic configurations for each protocol, making it adaptable to a wide range of scenarios. In essence, the parameter-based system provides a flexible and versatile solution for protecting DeFi protocols.
Protocol’s may choose to use one or multiple security parameter(s). Each security parameter is referenced by its creator (an address) and a unique identifier. These identifiers may be a token address, a hash, or any arbitrary Solidity bytes32 value. Said approach maximizes compatibility, by practically allowing protocol’s to track metrics for specific ERC20 tokens or other unique identifiers separately.
Nevertheless, this approach should not be confused with using multiple parameters (values) to compute a single security parameter. A security parameter may also be the result of a mathematical computation combining a set of multiple values.
Protective Measures
Once the firewall is triggered, protocols can use it in a variety of ways to protect their assets. Here are some of the protective measures that can be taken:
Block the Transaction: The protocol can choose to block the transaction that caused the parameter change. This is particularly useful in preventing unauthorized transactions that could potentially lead to fund theft.
Pause the Protocol: In some cases, the protocol might decide to pause all operations until the issue that caused the firewall to be triggered is resolved. This is a more drastic measure that can be used when the integrity of the entire protocol is at risk.
Freeze Affected Funds: If the transaction that triggered the firewall involves a withdrawal from the DeFi protocol, the protocol can freeze the funds affected by the transaction. This prevents the funds from being withdrawn until the issue is resolved. The funds can then be released upon the decision from a trusted third party for settling the dispute.
Throttle Fund Withdrawal: In some cases, the protocol might choose to throttle the withdrawal of funds to a smaller amount over time. This can be particularly useful in preventing large, suspicious withdrawals that could be indicative of a hack.
Implementation and Integration
TurtleShell is designed to be easily integrated into existing DeFi protocols. Its flexible and adaptable nature allows it to work seamlessly with a wide range of systems. Here's a brief guide on how to implement and integrate TurtleShell into your protocol:
Define Your Parameters: The first step is to define the parameters for your firewall. This includes the starting parameter, the time-period, and the threshold. The choice of parameters will depend on what you want to track and the specific needs of your protocol.
Integrate TurtleShell: Once you've defined your parameters, you can integrate TurtleShell into your protocol. This involves incorporating the TurtleShell smart contract into your protocol's codebase.
Monitor and Adjust: After integration, you can monitor the operation of the firewall and adjust the parameters as needed. This allows you to fine-tune the system to better protect your protocol.
Remember, the key to effective use of TurtleShell is understanding your protocol's specific needs and adjusting the parameters accordingly. With the right configuration, TurtleShell can provide a robust line of defense against potential hacks and unauthorized fund withdrawals.
Configuration
To configure the Firewall, protocol’s have to set the configuration parameters. These configuration values can be updated at any time.
Considerations
To ensure accurate operation of the Firewall, protocol’s have to include updating the security parameter frequently (on-chain), preferably whenever a dependency of it changes within its own state in storage.
To clarify, “dependency” means a dependency sub-parameter used to compute the security parameter (if the security is the result of multiple parameters using a formula, e.g. price rates, TVL), or the sole parameter (e.g. TVL) being used for the security parameter. This can be done on a per-transaction basis or a once per block basis, to ensure gas savings.
Nevertheless, how frequently the security parameter(s) is/are updated is - at the end - up to the protocol’s implementation. Therefore, integration can be highly individualistic.
Despite the automatic activation of the Firewall, protocol’s retain control over the status of the Firewall. They can manually deactivate or activate their Firewall at any given moment using a setFirewallStatus Solidity function.
Code modifications of the protocol
In general, the system is designed to work by only requiring moderate code manipulation at the protocol itself. In essence, implementing the Firewall requires including one function call to update the security parameter(s) wherever applicable within the protocol, while also checking the Firewall status before initiating TVL manipulations on the protocol (user withdrawals).
Whenever the Firewall gets triggered, protocol’s also have multiple options on what protective measures to enact as specified before. These would also have to be configured and integrated, as well.
Nevertheless, the amount of code manipulation needed heavily depends on the parameter’s used within the protocol to indicate malicious activity. Therefore, implementation work requirements can vary.
Last updated