How to Submit Pull Requests to Update links to Blockscout
This guide shows how to find and replace Etherscan links with Blockscout in open-source repos. Includes step-by-step GitHub pull request instructions, example commands, and proper domain mapping for Ethereum, Gnosis, Optimism, and more.
Open-source tools embody the fundamental principles of decentralization and transparency central to the blockchain. Blockscout, an open-source blockchain explorer, exemplifies these values by promoting transparency, community-driven development, and flexibility. Unlike proprietary explorers like Etherscan, Blockscout empowers users and developers to contribute to, customize, and adapt the explorer according to their specific needs.
This guide takes you through the process of identifying and updating block explorer links in any public repository, as well as how to submit a pull request (PR) to incorporate your enhancements. Whether you're contributing to a project you love in the DeFi space or improving your own, this upgrade allows for flexibility and promotes the use of open-source tools.
Why Replace Etherscan with Blockscout?
| Feature | Etherscan | Blockscout |
|---|---|---|
| Open Source | ❌ Closed | ✅ Fully Open |
| Self-Hosted Option | ❌ No | ✅ Yes |
| Community Friendly | Commercial-focused | ✅ Built for ecosystems |
Prerequisites
Before you start, ensure you have:
- A GitHub account
- Git installed locally (or use GitHub's web UI)
- Familiarity with basic Git commands (or use GitHub's interface)
- The repository you want to contribute to (either forked or cloned)
Step 1: Search the Repo for Explorer Links
This part can be tricky because in larger monorepos or ecosystems with many sub-repos explorer links can be scattered and hard to locate.
One way to solve this is using ripgrep a blazing-fast command-line search tool that respects .gitignore by default, and is ideal for large codebases.
Install ripgrep, enter the root of your project and run;
rg etherscan.io
Step 2: Replace Links with Blockscout URLs
Use the correct Blockscout domain for the chain you're working with. Here’s a quick mapping:
| Chain | Etherscan Equivalent | Blockscout Equivalent |
|---|---|---|
| Ethereum Mainnet | etherscan.io |
eth.blockscout.com |
| Gnosis | gnosisscan.io |
gnosis.blockscout.com |
| Optimism | optimistic.etherscan.io |
optimism.blockscout.com |
| Polygon | polygonscan.com |
polygon.blockscout.com |
| Base | basescan.org |
base.blockscout.com |
Step 3: Test Your Changes
Before committing:
- Check that all links work
- Validate that the target address or transaction matches the correct chain.
- Ensure no broken markdown, JSX, or HTML rendering
Step 4: Commit and push
Create a new branch, commit and push with these commands.
git checkout -b replace-etherscan-with-blockscout
git add .
git commit -m "chore: replaced block explorer links with Blockscout"
git push origin replace-etherscan-with-blockscout
Step 5: Submit a Pull Request
- Go to your GitHub fork
- Click “Compare & pull request”
- Fill in the PR form:
Once you submit your pull request, it’s important to allow time for the repository maintainers to evaluate your proposed changes. During this review phase, they may request adjustments or additional information; therefore, be sure to respond promptly and make any necessary updates. After your pull request is approved, it will be merged into the main codebase.
Example - Velodrome Finance Relay
We will be updating the Velodrome Finance Relay README file to replace the current Etherscan links with Blockscout links for the tokens. Velodrome is a decentralized exchange that facilitates low-fee token swaps, allows users to deposit tokens for rewards, and enables active participation in the on-chain economy.
Step 1: Fork and Clone the Repository
Navigate to the Velodrome Finance GitHub and fork the Velodrome Relay repository. Next, clone your forked repository to your local machine.
Run;
git clone https://github.com/your-username/repository-name.git
cd repository-name
Step 2: Create a New Branch
Create and switch to a new branch for your changes
Run;
git checkout -b update-blockscout-links
Step 3: Identify Etherscan Links Using ripgrep
Use ripgrep to search for all occurrences of Etherscan links:
Run;
rg -uuu 'etherscan'
Step 4: Replace Etherscan Links with Blockscout
Use sed or manually edit the files to replace Etherscan URLs with Blockscout equivalents.
Run;
sed -i 's/https:\/\/etherscan\.io/https:\/\/blockscout.com/g' $(rg -l 'https?://(www\.)?etherscan\.io')
Test and ensure that the replacement URLs are accurate and direct users to the corresponding Blockscout pages.
Step 5: Commit Your Changes
Stage and commit your changes with a clear message:
Run;
git add .
git commit -m "Replace Etherscan links with Blockscout"
Step 6: Push and Create a Pull Request
Push your branch to your forked repository:
Run;
git push origin update-blockscout-links
Go to your fork on GitHub and create a pull request to the original Velodrome Finance repository.
Conclusion
While centralized explorers like Etherscan are efficient and widely used, switching to Blockscout encourages projects to adopt more transparent and open infrastructure. It’s a practical way to uphold the principles of decentralization and openness values that are often discussed in Web3 but not always reflected in tooling choices.
Blockscout is fully open-source, supports multiple EVM chains, and can be self-hosted by any project or community. By updating explorer links, you decrease reliance on closed services and make it easier for others to audit, extend, or run their own instances. Small contributions like this strengthen the foundation of an open and resilient blockchain ecosystem.