TurtleShellFirewall
TurtleShellFirewall Contract
The TurtleShellFirewall smart contract is the core of the TurtleShell Firewall system. It can be utilized by any contract to implement an on-chain firewall.
Table of Contents
Description
The firewall can be set up by the contract owner to define a threshold percentage, block interval, and start parameter. When a given user's parameter changes by more than the set threshold, the firewall gets triggered for that user. The firewall can be manually deactivated or activated by the user at any given moment.
The ITurtleShellFirewall and ITurtleShellFirewallIncreaser interfaces are part of an SDK that provides a set of security measures for users in a blockchain network. These measures are designed as a 'firewall' to monitor and control user interactions within a protocol based on specific parameters.
The firewall configuration can be set up by the contract owner to define a set of rules that include a threshold percentage, block interval, start parameter, and a cooldown period. These parameters work together to create a dynamic firewall system.
The threshold percentage defines the maximum limit, which a parameter is allowed to change in a given time window.
The block interval defines the number of blocks (time window) within the parameter should not change by more than the threshold percentage.
The start parameter is the starting security parameter for a given protocol’s security parameter.
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.
When a given user's parameter changes by more than the set threshold, the firewall gets triggered for that user. It will remain active for the number of blocks defined in the block interval. While the firewall is active, it can monitor and potentially limit the user's interactions within the protocol to prevent any malicious activities or drastic changes.
Despite the automatic activation, users retain control over the status of the firewall. They can manually deactivate or activate their firewall at any given moment using the setFirewallStatus function.
For even finer control, users can use the ITurtleShellFirewallIncreaser extension. This interface provides two additional methods (increaseParameter and decreaseParameter) that allow users to adjust their security parameters up or down within the firewall's rules.
These interfaces offer a powerful tool for maintaining security in a blockchain protocol. By adjusting and monitoring user parameters, the firewall can help prevent abrupt changes that might signal malicious behavior, providing a more secure environment for all users.
Structures
FirewallConfig
The FirewallConfig struct contains the configuration values for the firewall of a given user.
thresholdPercentage: This is the change threshold as a percentage, represented as an integer.blockInterval: This is the number of blocks that the firewall "rewinds" to find the reference parameter for the firewall check.cooldownPeriod: This is the number of blocks the system waits before turning off the firewall once it has been triggered.
ParameterData
The ParameterData struct holds the dynamic data related to a user's parameter:
parameter: The user's parameter value.blockNumber: The block number when this parameter was set.
FirewallData
The FirewallData struct contains the dynamic data related to the firewall's state for a given user:
parameters: A mapping of nonce values toParameterData.firewallActive: A boolean indicating if the firewall is currently active for the user.nonce: A nonce value for the parameters mapping.lastActivatedBlock: The block number when the firewall was last activated.
Methods
Public Methods
setParameter: Any user can call this function to update their security parameter. If the parameter exceeds the threshold, the firewall is automatically activated. If the firewall is already active, the parameter will be updated anyway.increaseParameter: This function allows any user to increase their security parameter.decreaseParameter: This function allows any user to decrease their security parameter.setUserConfig: This function allows the user to set the configuration values for their firewall.
External Methods
setFirewallStatus: This function sets the firewall status.getFirewallStatusOf: This function returns the firewall status of a specific user.getParameterOf: This function returns the parameter of a specific user.getSecurityParameterConfigOf: This function returns the security parameter config of a specific user.
Internal Methods
_setParameter: This function is used internally to set the parameter for a given user._setFirewallStatus: This function is used internally to set the firewall status for a given user._checkIfParameterUpdateExceedsThreshold: This function is used internally to check if the parameter update is below the threshold.
Events
ParameterChanged: This event is emitted when a user's parameter has been changed.FirewallStatusUpdate: This event is emitted when a user's firewall status is updated.
Error Handling
The contract uses Solidity's custom errors for error handling:
TurtleShellFirewall__InvalidThresholdValue: Emitted if the threshold value is greater than 100 (100%).TurtleShellFirewall__InvalidBlockInterval: Emitted if the block interval is greater than the total number of blocks.TurtleShellFirewall__InvalidCooldownPeriod: Emitted if the cooldown period is greater than the total number of blocks.TurtleShellFirewall__InvalidConfigValues: Emitted if the startParameter is too big to be multiplied by the threshold percentage.TurtleShellFirewall__CannotHaveNegativeParameter: Emitted if the parameter is decreased below zero.
Last updated