{"id":28491298,"url":"https://github.com/pcaversaccio/white-hat-frontrunning","last_synced_at":"2025-07-04T23:32:03.639Z","repository":{"id":258304088,"uuid":"872022825","full_name":"pcaversaccio/white-hat-frontrunning","owner":"pcaversaccio","description":"White hat frontrunning script to outpace hackers and secure funds from compromised wallets.","archived":false,"fork":false,"pushed_at":"2025-06-22T10:07:55.000Z","size":59,"stargazers_count":125,"open_issues_count":0,"forks_count":23,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-22T11:19:43.900Z","etag":null,"topics":["flashbots","frontrunning-attacks","white-hat"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pcaversaccio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2024-10-13T15:31:35.000Z","updated_at":"2025-06-22T10:07:58.000Z","dependencies_parsed_at":"2025-02-08T11:19:09.497Z","dependency_job_id":"b6e07587-e6cf-4f05-a1b1-470a1e456f5f","html_url":"https://github.com/pcaversaccio/white-hat-frontrunning","commit_stats":null,"previous_names":["pcaversaccio/white-hat-frontrunning"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pcaversaccio/white-hat-frontrunning","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pcaversaccio%2Fwhite-hat-frontrunning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pcaversaccio%2Fwhite-hat-frontrunning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pcaversaccio%2Fwhite-hat-frontrunning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pcaversaccio%2Fwhite-hat-frontrunning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pcaversaccio","download_url":"https://codeload.github.com/pcaversaccio/white-hat-frontrunning/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pcaversaccio%2Fwhite-hat-frontrunning/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263635745,"owners_count":23492257,"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":["flashbots","frontrunning-attacks","white-hat"],"created_at":"2025-06-08T08:06:53.538Z","updated_at":"2025-07-04T23:32:03.628Z","avatar_url":"https://github.com/pcaversaccio.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🥷🏽 White Hat Frontrunning\n\n[![License: AGPL-3.0-only](https://img.shields.io/badge/License-AGPL--3.0--only-blue)](https://www.gnu.org/licenses/agpl-3.0)\n\nWhite hat frontrunning [script](./go.sh) to outpace hackers and secure funds from compromised wallets. The (Bash) [script](./go.sh) is intentionally designed with minimal dependencies, requiring only the native tools provided by Linux and [`cast`](https://github.com/foundry-rs/foundry/tree/master/crates/cast) from [Foundry](https://github.com/foundry-rs/foundry).\n\n## Usage\n\n\u003e [!NOTE]\n\u003e Ensure that [`cast`](https://github.com/foundry-rs/foundry/tree/master/crates/cast) is installed locally. For installation instructions, refer to this [guide](https://getfoundry.sh/introduction/installation/).\n\nFirst, modify the main loop in the [script](./go.sh). At present, it's set to send gas to a victim wallet and transfer a specific token. Since the main loop needs to be tailored for each rescue, please review and adjust it carefully.\n\nNext, make the [script](./go.sh) executable:\n\n```console\nchmod +x go.sh\n```\n\n\u003e [!TIP]\n\u003e The [script](./go.sh) is already set as _executable_ in the repository, so you can run it immediately after cloning or pulling the repository without needing to change permissions.\n\nNow it's time to configure the `.env` accordingly (this is an illustrative `.env` file):\n\n\u003e [!CAUTION]\n\u003e The private keys below are placeholders and should never be used in a production environment!\n\n```txt\nPROVIDER_URL=\"https://rpc.flashbots.net\"\nRELAY_URL=\"https://relay.flashbots.net\"\nVICTIM_PK=\"0x1234567890\"\nGAS_PK=\"0x9876543210\"\nFLASHBOTS_SIGNATURE_PK=\"0x31337\"\nTOKEN_CONTRACT=\"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\"\n```\n\n\u003e [!TIP]\n\u003e When submitting bundles to Flashbots, they are signed with your `FLASHBOTS_SIGNATURE_PK` key, enabling Flashbots to verify your identity and track your [reputation](https://docs.flashbots.net/flashbots-auction/advanced/reputation) over time. This reputation system is designed to safeguard the infrastructure from threats such as DDoS attacks. It's important to note that this key **does not** handle any funds and is **not** required to be the primary Ethereum key used for transaction authentication. Its sole purpose is to establish your identity with Flashbots. You can use any ECDSA `secp256k1` key for this, and if you need to create a new one, you can use [`cast wallet new`](https://getfoundry.sh/cast/reference/cast-wallet-new/).\n\nFinally, execute the [script](./go.sh):\n\n```console\n./go.sh\n```\n\nTo enable _debug mode_, set the `DEBUG` environment variable to `true` before running the [script](./go.sh):\n\n```console\nDEBUG=true ./go.sh\n```\n\nThis will print each command before it is executed, which is helpful when troubleshooting.\n\n## EIP-7702-Based Rescue\n\nUsing [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702), you can rescue all funds from a compromised wallet using a paymaster and a friendly delegator. There is _no need_ to send ether to the compromised wallet at all. The script [`go_eip7702.sh`](./go_eip7702.sh) handles the full rescue logic. It deploys a Vyper contract called [`recoverooor.vy`](./recoverooor.vy), which acts as the (friendly) delegator to facilitate the asset transfers. All you need to do is set the environment variables `RPC_URL`, `VICTIM_PK`, and `PAYMASTER_PK`, along with the `PAYLOAD` parameter containing the calldata to be executed by the delegator contract.\n\n\u003e [!TIP]\n\u003e To generate the same bytecode for [`recoverooor.vy`](./recoverooor.vy) as the script [`go_eip7702.sh`](./go_eip7702.sh), install the necessary dependencies via `pip install vyper==0.4.2 snekmate==0.1.2rc1` and compile the contract using `vyper recoverooor.vy`.\n\nTo get started, configure your `.env` file as shown below:\n\n\u003e [!CAUTION]\n\u003e The private keys below are placeholders and should never be used in a production environment!\n\n```txt\nRPC_URL=\"https://rpc.flashbots.net\"\nVICTIM_PK=\"0x1234567890\"\nPAYMASTER_PK=\"0xba5Ed\"\n```\n\nThe `PAYLOAD` parameter in the script [`go_eip7702.sh`](./go_eip7702.sh) must be the calldata that calls the [`recoverooor.vy`](./recoverooor.vy) contract with the appropriate logic (refer to the [`encode_recover_multicall.sh`](./encode_recover_multicall.sh) script for details on how to encode calldata for the `recover_multicall` function). The [`recoverooor.vy`](./recoverooor.vy) contract will be deployed with the paymaster wallet as the `OWNER`. The [`script`](./go_eip7702.sh) also resets the [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) authorisation at the end, in case the `OWNER` can no longer be trusted in the future.\n\nTo perform the rescue, simply run:\n\n```console\n./go_eip7702.sh\n```\n\nTo enable _debug mode_, set the `DEBUG` environment variable to `true` before running the [script](./go_eip7702.sh):\n\n```console\nDEBUG=true ./go_eip7702.sh\n```\n\nThis will print each command before it is executed, which is helpful when troubleshooting.\n\n\u003e [!TIP]\n\u003e To make an authorisation replayable across all chains, simply set the chain ID to `0` (see [here](https://eips.ethereum.org/EIPS/eip-7702#protection-from-malleability-cross-chain)). While `cast` does not currently support this feature, you can use my [`ethers`](https://docs.ethers.org/v6/)-based [script](https://github.com/pcaversaccio/raw-tx/blob/bd86ddb1311bffe8e24ddea961bc09e4952cf4f6/scripts/sign-eip7702.ts#L61-L73) to generate a replayable authorisation. This authorisation can then be passed into the main [script](./go_eip7702.sh).\n\n## Community Examples\n\n\u003e [!WARNING]\n\u003e I have reviewed these examples as part of the PR process, but they haven't been fully tested. Please ensure a thorough review before using them!\n\nThe [`community-examples/`](./community-examples/) directory contains customised versions of the primary [`go.sh`](./go.sh) script, tailored for a variety of rescue scenarios.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpcaversaccio%2Fwhite-hat-frontrunning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpcaversaccio%2Fwhite-hat-frontrunning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpcaversaccio%2Fwhite-hat-frontrunning/lists"}