Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feat/docs for v6 to v7 #280

Merged
merged 3 commits into from
Apr 9, 2025
+145 −41
Merged

Feat/docs for v6 to v7 #280

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eb16ea3
modify docs for v6 -> v7
girafferz Mar 28, 2025
5650387
docs for v6 -> v7 migrate
girafferz Apr 1, 2025
6ca56ba
modify for review
girafferz Apr 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 145 additions & 41 deletions docs/verse-developer/2-how-to-build-verse/explorer.md
View file
Original file line number Diff line number Diff line change
@@ -57,48 +57,110 @@ If you are using op-geth, follow these steps to enable the required namespaces:
- Restart your `op-geth` node to apply the settings
- Check the logs to confirm the namespaces are available

## Common Backend Environment Variables
Both BlockScout v6 and v7 share the following environment variables that need to be configured:
## Blockscout v7

For more details, see [Blockscout Backend Environment Variables](https://docs.blockscout.com/setup/env-variables/backend-env-variables).
### Setup Blockscout
#### Backend Setup
1. **Clone Repository**:
```shell
git clone https://github.com/oasysgames/blockscout-v7-backend.git
cd blockscout-v7-backend
```

| Variable | Description | Value |
|---------------------------|--------------------------------------------|--------|
| DATABASE_URL | Postgres Database endpoint | postgresql://postgres:@host.docker.internal:7432/blockscout?ssl=falset |
| ETHEREUM_JSONRPC_VARIANT | RPC Client type | geth |
| ETHEREUM_JSONRPC_HTTP_URL | RPC endpoint for main operations | rpc.myverse.com |
| ETHEREUM_JSONRPC_TRACE_URL | RPC endpoint for tracing operations. This endpoint must support debug_traceTransaction method for internal transactions. For Verse v1 (OP Stack), ensure that the debug namespace is enabled and the node is configured to support internal transaction tracing. | rpc.myverse.com |
| SECRET_KEY_BASE | Random string for contract verification | Generate using: `head -c 64 /dev/urandom \| base64 \| cut -c 1-64` |
| JSON_RPC | RPC endpoint for MetaMask integration | rpc.myverse.com |
| CHAIN_ID | Chain ID for MetaMask integration | Your Verse ChainID |
| RE_CAPTCHA_SECRET_KEY | reCAPTCHA secret key | Your secret key |
| RE_CAPTCHA_CLIENT_KEY | reCAPTCHA client key | Your client key |
2. **Checkout Specific Version**:
Check available versions at [blockscout-v7-backend releases](https://github.com/oasysgames/blockscout-v7-backend/tags) and checkout the desired version:
```shell
# Example: checking out the latest stable version
git checkout <version-tag>
```

Note: If running on the same server, use `http://host.docker.internal:8545/` for RPC URLs.
3. **Configure Environment Variables and Start**:
Set the following variables in [common-blockscout.env](https://github.com/oasysgames/blockscout-v7-backend/blob/main/docker-compose/envs/common-blockscout.env):

## Frontend Environment Variables
Both BlockScout v6 and v7 share the following frontend environment variables that need to be configured:
```shell
cd docker-compose/envs/
vim common-blockscout.env
docker compose build
docker compose up -d
```

:::note Important Notes for Verse v1 Environment
When setting up Blockscout for Verse v1 (OP Stack), ensure the following configuration:
Refer to the [Common Backend Environment Variables](#common-backend-environment-variables) section below for the required configuration.

1. Set `NEXT_PUBLIC_VERSE_VERSION=1` to enable OP Stack specific features
2. Set `NEXT_PUBLIC_HOMEPAGE_HIDDEN_OP_NODE_TXS=true` to hide internal L2 transactions (recommended for cleaner transaction view)
:::
4. **Run Backend Container**:
```shell
sudo FRONT_PROXY_PASS=http://host.docker.internal:3000 docker compose -f external-frontend.yml up -d
```

For more common details, see [Blockscout Frontend Environment Variables](https://docs.blockscout.com/for-developers/information-and-settings/env-variables/frontend-common-envs).
#### Frontend Setup
1. **Clone Repository**:
```shell
git clone https://github.com/oasysgames/blockscout-v7-frontend.git
cd blockscout-v7-frontend
```

### OP Stack Related Variables
| Variable | Description | Value |
|---------------------------|--------------------------------------------|--------|
| NEXT_PUBLIC_HOMEPAGE_HIDDEN_OP_NODE_TXS | Controls the visibility of OP Stack transactions. When enabled, it hides L2 transactions from the OP Stack node . This is particularly useful for Verse v1 which uses OP Stack. | `true` or `false` |
| NEXT_PUBLIC_VERSE_VERSION | Specifies the Verse version. Set to `1` for Verse v1 (OP Stack) or `0` for Verse v0 (L2Geth). This affects how bridge transactions and other version-specific features are handled in the explorer. | `0` or `1` |
2. **Checkout Specific Version**:
Check available versions at [blockscout-v7-frontend releases](https://github.com/oasysgames/blockscout-v7-frontend/tags) and checkout the desired version:
```shell
# Example: checking out the latest stable version
git checkout <version-tag>
```

### Token Configuration Variables
| Variable | Description | Value | Version |
|---------------------------|--------------------------------------------|--------|---------|
| NEXT_PUBLIC_RE_CAPTCHA_APP_SITE_KEY | reCAPTCHA site key for the application. Note: In versions prior to v1.38.x, this was temporarily named as `NEXT_PUBLIC_RE_CAPTCHA_V3_APP_SITE_KEY`. From v1.38.x onwards, it has been reverted back to `NEXT_PUBLIC_RE_CAPTCHA_APP_SITE_KEY`. | Your reCAPTCHA site key | All |
| NEXT_PUBLIC_UPDATED_TOKENS | URL of a JSON configuration file or a JSON string containing updated token information. Used to override token display information in the explorer. | URL: `https://oasys-blockscout-networks.s3.ap-northeast-1.amazonaws.com/blockscout-updated-tokens.json` or JSON string: `{"tokens":[{"address":"0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000","name":"Oasys","symbol":"OAS"},{"address":"0xE1aB220E37AC55A4E2dD5Ba148298A9c09fBD716","name":"Legacy Bridged USDC (Celer)","symbol":"USDC.e-legacy"}]}` | v1.38.x+ |
3. **Configure Environment Variables**:
- Set variables in [.env.common](https://github.com/oasysgames/blockscout-v7-frontend/blob/main/configs/envs/.env.common)
- For available options, see [Blockscout v7 Frontend Documentation](https://github.com/oasysgames/blockscout-v7-frontend/blob/main/docs/ENVS.md)
- For Featured Networks configuration, see [Featured Network Configuration Properties](https://github.com/blockscout/frontend/blob/main/docs/ENVS.md#featured-network-configuration-properties)
- For OP Stack configuration, see [OP Stack Related Variables](#op-stack-related-variables)
- For Token configuration, see [Token Configuration Variables](#token-configuration-variables)

4. **Run Frontend Container**:
```shell
docker-compose build
docker compose up -d
```

Access the explorer at `http://localhost/` or `http://localhost:3000/`

## Migrating from Blockscout v6 to v7

This section guides you through the process of migrating your Blockscout explorer from version 6 to version 7.

### Repository Changes

When migrating from v6 to v7, you'll need to use different repositories:

**Frontend:**
- v6: `github.com/oasysgames/blockscout-v6-frontend`
- v7: `github.com/oasysgames/blockscout-v7-frontend`

**Backend:**
- v6: `github.com/oasysgames/blockscout-v6-backend`
- v7: `github.com/oasysgames/blockscout-v7-backend`

### Migration Steps

1. Stop the v6 services:
```bash
# In the v6 directory
docker-compose down
```

2. Start the v7 services:
```bash
# In the v7 directory
docker-compose up -d
```

### Environment Variable Changes

When migrating to v7, note the following environment variable changes:

**reCAPTCHA Configuration:**
- v6: `NEXT_PUBLIC_RE_CAPTCHA_V3_APP_SITE_KEY`
- v7: `NEXT_PUBLIC_RE_CAPTCHA_APP_SITE_KEY`

Make sure to update your environment configuration accordingly.

The migration process from v6 to v7 is designed to be automatic, and verified contracts will also be carried over automatically.

## Blockscout v6

@@ -127,7 +189,7 @@ For more common details, see [Blockscout Frontend Environment Variables](https:/
docker compose up -d
```

Refer to the [Common Backend Environment Variables](#common-backend-environment-variables) section above for the required configuration.
Refer to the [Common Backend Environment Variables](#common-backend-environment-variables) section below for the required configuration.

4. **Run Backend Container**:
```shell
@@ -163,8 +225,6 @@ For more common details, see [Blockscout Frontend Environment Variables](https:/

Access the explorer at `http://localhost/` or `http://localhost:3000/`

#### Optional: Migrate Verified Contract Data
If you want to migrate verified contract data from v5 to v6:

```shell
cd blockscout-v6-backend/migrates/
@@ -174,22 +234,66 @@ sudo chmod +x excutes/verified_contract.sh
./excutes/verified_contract.sh
```

### Post-Build Verification
Perform these checks to ensure proper operation:
## Common Configuration Items

### Common Backend Environment Variables
Both BlockScout v6 and v7 share the following environment variables that need to be configured:

For more details, see [Blockscout Backend Environment Variables](https://docs.blockscout.com/setup/env-variables/backend-env-variables).

| Variable | Description | Value |
|---------------------------|--------------------------------------------|--------|
| DATABASE_URL | Postgres Database endpoint | postgresql://postgres:@host.docker.internal:7432/blockscout?ssl=falset |
| ETHEREUM_JSONRPC_VARIANT | RPC Client type | geth |
| ETHEREUM_JSONRPC_HTTP_URL | RPC endpoint for main operations | rpc.myverse.com |
| ETHEREUM_JSONRPC_TRACE_URL | RPC endpoint for tracing operations. This endpoint must support debug_traceTransaction method for internal transactions. For Verse v1 (OP Stack), ensure that the debug namespace is enabled and the node is configured to support internal transaction tracing. | rpc.myverse.com |
| SECRET_KEY_BASE | Random string for contract verification | Generate using: `head -c 64 /dev/urandom \| base64 \| cut -c 1-64` |
| JSON_RPC | RPC endpoint for MetaMask integration | rpc.myverse.com |
| CHAIN_ID | Chain ID for MetaMask integration | Your Verse ChainID |
| RE_CAPTCHA_SECRET_KEY | reCAPTCHA secret key | Your secret key |
| RE_CAPTCHA_CLIENT_KEY | reCAPTCHA client key | Your client key |

Note: If running on the same server, use `http://host.docker.internal:8545/` for RPC URLs.

## Frontend Environment Variables
Both BlockScout v6 and v7 share the following frontend environment variables that need to be configured:

:::note Important Notes for Verse v1 Environment
When setting up Blockscout for Verse v1 (OP Stack), ensure the following configuration:

1. Set `NEXT_PUBLIC_VERSE_VERSION=1` to enable OP Stack specific features
2. Set `NEXT_PUBLIC_HOMEPAGE_HIDDEN_OP_NODE_TXS=true` to hide internal L2 transactions (recommended for cleaner transaction view)
:::

For more common details, see [Blockscout Frontend Environment Variables](https://docs.blockscout.com/for-developers/information-and-settings/env-variables/frontend-common-envs).

### OP Stack Related Variables
| Variable | Description | Value |
|---------------------------|--------------------------------------------|--------|
| NEXT_PUBLIC_HOMEPAGE_HIDDEN_OP_NODE_TXS | Controls the visibility of OP Stack transactions. When enabled, it hides L2 transactions from the OP Stack node . This is particularly useful for Verse v1 which uses OP Stack. | `true` or `false` |
| NEXT_PUBLIC_VERSE_VERSION | Specifies the Verse version. Set to `1` for Verse v1 (OP Stack) or `0` for Verse v0 (L2Geth). This affects how bridge transactions and other version-specific features are handled in the explorer. | `0` or `1` |

### Token Configuration Variables
| Variable | Description | Value | Version |
|---------------------------|--------------------------------------------|--------|---------|
| NEXT_PUBLIC_RE_CAPTCHA_APP_SITE_KEY | reCAPTCHA site key for the application. Note: In versions prior to v1.38.x, this was temporarily named as `NEXT_PUBLIC_RE_CAPTCHA_V3_APP_SITE_KEY`. From v1.38.x onwards, it has been reverted back to `NEXT_PUBLIC_RE_CAPTCHA_APP_SITE_KEY`. | Your reCAPTCHA site key | All |
| NEXT_PUBLIC_UPDATED_TOKENS | URL of a JSON configuration file or a JSON string containing updated token information. Used to override token display information in the explorer. | URL: `https://oasys-blockscout-networks.s3.ap-northeast-1.amazonaws.com/blockscout-updated-tokens.json` or JSON string: `{"tokens":[{"address":"0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000","name":"Oasys","symbol":"OAS"},{"address":"0xE1aB220E37AC55A4E2dD5Ba148298A9c09fBD716","name":"Legacy Bridged USDC (Celer)","symbol":"USDC.e-legacy"}]}` | v1.38.x+ |

## Testing Items

#### UI Functionality
### UI Functionality
- [x] CSV downloads work without errors
- [x] Logos display correctly in both light/dark modes
- [x] Network list is accurate
- [x] MetaMask integration works properly

#### Core Features
### Core Features
- [x] Smart Contract verification (GUI and API)
- [x] REST API and GraphQL endpoints
- [x] Wallet Connect integration
- [x] Internal transactions retrieval

#### System Health
### System Health
- [x] Monitor CPU and memory usage
- [x] Check storage usage and alerts
- [x] Verify PostgreSQL database performance