{"id":20640522,"url":"https://github.com/kovart/forta-gas-agent","last_synced_at":"2025-04-15T23:01:31.591Z","repository":{"id":97652075,"uuid":"490895910","full_name":"kovart/forta-gas-agent","owner":"kovart","description":"⛽  The agent helps to detect unusual high gas usage for the specified protocols. ","archived":false,"fork":false,"pushed_at":"2022-06-03T09:33:14.000Z","size":2183,"stargazers_count":4,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T02:21:46.484Z","etag":null,"topics":["agent","attack","ethereum","forta","gas","holt-winters"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kovart.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-10T23:53:36.000Z","updated_at":"2022-10-21T04:49:09.000Z","dependencies_parsed_at":"2023-03-23T09:17:56.039Z","dependency_job_id":null,"html_url":"https://github.com/kovart/forta-gas-agent","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kovart%2Fforta-gas-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kovart%2Fforta-gas-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kovart%2Fforta-gas-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kovart%2Fforta-gas-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kovart","download_url":"https://codeload.github.com/kovart/forta-gas-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249167446,"owners_count":21223506,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","attack","ethereum","forta","gas","holt-winters"],"created_at":"2024-11-16T15:29:46.745Z","updated_at":"2025-04-15T23:01:31.572Z","avatar_url":"https://github.com/kovart.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Anomalous Gas Usage Agent\n\n## Description\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Ronin Bridge gas usage\" src=\"./blob/ronin-bridge.png\"\u003e\n\u003c/p\u003e\n\nThis agent helps to detect unusual high gas usage for the specified protocols.\nAt the moment, the agent analyses only the value of `priorityFeePerGas` ([EIPS-1559](https://eips.ethereum.org/EIPS/eip-1559)),\nwhich is calculated according the following formula:\n\n```\npriorityFeePerGas = min(transaction.maxPriorityFeePerGas, transaction.maxFeePerGas - block.baseFeePerGas)\n```\n\nThe main analyser `holt-winters` works with the following algorithm: \n1. Group the data by hours _(13:00, 14:00, 15:00, ...)_\n2. Choose the maximal values of `priorityFeePerGas` for each group\n3. Interpolate the values for the empty hours using the easy function **f(x) = x^5**\n4. Reduce noise values with Kalman filter\n5. Create the forecast with [Holt-Winters method](https://otexts.com/fpp2/holt-winters.html)\n6. Measure deviation of real and expected values\n7. If the deviation is greater than the `changeRate` then fire an alert\n\nThe Holt-Winters analyser starts checking transactions as soon as it has enough training data,\nwhich it collects during 2 (seasons) * 7 (days) * 24 (hours) = 332 hours.\n\n---\n\nThe agent has a fairly powerful system of working with analysers, but at the moment, only one is available (Holt-Winters).\nIt is possible to use the same analysers, but with different parameters. For example, you can initialize the Moving Avarage analysers with different order parameters.\n\n---\n\nTo see live how the algorithm works with different protocols and data, see [research folder](./research).\nThe demo server can be started with the command:\n\n```bash\ncd ./research/\nnpm run start\n```\n\n## Supported Chains\n\nEVM-compatible chains that support [EIPS-1559](https://eips.ethereum.org/EIPS/eip-1559).\n\n## Features\n\n- Support for multiple analysers\n- Support for protocol-specific configurations\n- Values interpolation for contracts with irregular transactions\n- Noise values filtering to improve prediction accuracy\n- Demo server with real-world data and prediction results\n\n## Analysers\n\n### Holt-Winters\n\n**Key:** \"holt-winters\"\n\n#### Configuration\n\n- `alpha` сoefficient for the level smoothing Defau _(optional)_ \u0026nbsp;|\u0026nbsp; Default: **0**\n- `gamma` сoefficient for the trend smoothing _(optional)_ \u0026nbsp;|\u0026nbsp; Default: **0**\n- `delta` сoefficient for the seasonal smoothing _(optional)_ \u0026nbsp;|\u0026nbsp; Default: **0**\n- `changeRate` minimum difference rate after which the value is considered anomalous, e.g. 0.5 = 50%, 3 = 300% _(required)_ \u0026nbsp;|\u0026nbsp; Default: **3**\n- `trainingCycles` number of iterations for selecting optimal сoefficients _(required)_ \u0026nbsp;|\u0026nbsp; Default: **20**\n- `seasonLength` number of values per season _(required)_ \u0026nbsp;|\u0026nbsp; Default: 7 (days) \\* 24 (hours) = **168** (hours)\n\n## Alerts\n\n- KOVART-ANOMALOUS-PRIORITY-FEE-HOLT-WINTERS\n  - Fired when a transaction actual `priorityFeePerGas` is greater the predicted by more than 300%\n  - Severity is always set to \"medium\"\n  - Type is always set to \"suspicious\"\n  - metadata:\n    - `sender` sender address\n    - `actualPriorityFeePerGas` actual value in Gwei\n    - `expectedPriorityFeePerGas` predicted value in Gwei\n\n## Test Data\n\nThe agent behaviour can be checked in the [demo project](./research).\n\nSince [default config](./agent-config.json) contains Ronin Bridge contract, \nthe following command catch [the Ronin Hack](https://forta.org/blog/ronin-hack/):\n\n```bash\nnpm run range 14342885..14442835\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkovart%2Fforta-gas-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkovart%2Fforta-gas-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkovart%2Fforta-gas-agent/lists"}