Skip to content
Permalink

Comparing changes

This is a direct comparison between two commits made in this repository or its related repositories. View the default comparison for this range or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: blockscout/blockscout-rs
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: d3060b3fdfda930fccc6d6db253fc8f7403e6d78
Choose a base ref
..
head repository: blockscout/blockscout-rs
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: 864c804a0f8d993df27ce277f389b49f417b39a9
Choose a head ref
65 changes: 55 additions & 10 deletions blockscout-ens/README.md
Original file line number Diff line number Diff line change
@@ -8,6 +8,20 @@ Here is brief overview of the project structure:

Service is **multi-chain**, meaning that only one instance of `graph-node`, `postgres` and `bens-server` is required.

## Current supported domains

| Subgraph Name | Network | TLD | Note |
|--------------|---------|-----|------|
| ens-subgraph | Ethereum | .eth | |
| rns-subgraph | Rootstock | .rsk | |
| genome-subgraph | Gnosis | .gno | SpaceID contracts |
| bns-subgraph | Base | .base | |
| mode-subgraph | Mode | .mode | SpaceID contracts |
| lightlink-subgraph | Lightlink | .ll | SpaceID contracts |
| zns-subgraph | Polygon | .poly | |
| d3-connect-subgraph | Shibarium | .shib | |


## Envs

[anchor]: <> (anchors.envs.start.envs_main)
@@ -26,21 +40,52 @@ Service is **multi-chain**, meaning that only one instance of `graph-node`, `pos

[anchor]: <> (anchors.envs.end.envs_main)

## Quickstart developer run

1. Install [just](https://github.com/casey/just), [dotenv-cli](https://www.npmjs.com/package/dotenv-cli)

2. Run commands:
```bash
just graph-node-start
just deploy-subgraph ens-sepolia
just run-dev
```


## Contribute

If you want to add your name service procol to blockscout you should:

1. Clone this `blockscout-rs` repo to add new protocol.
1. Write subraph code: read [subgraph writer guide](./graph-node/subgraph-writer/README.md#howto-create-subgraph-for-your-domain-name-protocol)
1. [OPTIONAL] if your protocol is based on SpaceID, read [SpaceID integration](./graph-node/subgraphs/README.md#spaceid-integration) section.
1. Start graph-node: read [graph-node guide](./graph-node/README.md#start-locally-using-docker-compose)
1. Deploy subgraph to graph-node: read [how to deploy subgraphs guide](./graph-node/subgraphs/README.md#deploy-subgraph-to-graph-node)
1. Update default config of BENS server for [production](../../bens-server/config/prod.json) and [staging](../../bens-server/config/staging.json)
1. Start `bens-server` connected to common database: read [how to start bens guide](./bens-server/README.md#to-start-locally)
1. Check that `bens-server` responses with valid domains
1. Add your protocol to list of [supported domains](./graph-node/subgraphs/README.md#current-supported-domains)
1. Finally, create PR with:
2. Write subraph code: read [subgraph writer guide](./graph-node/subgraph-writer/README.md#howto-create-subgraph-for-your-domain-name-protocol)
3. [OPTIONAL] if your protocol is based on SpaceID, read [SpaceID integration](./graph-node/README.md#spaceid-integration) section.
4. Add your protocol to deployment config [config.json](./graph-node/deployer/config.json)
5. Start graph-node (more in [graph-node guide](./graph-node/README.md#start-locally-using-docker-compose)):

```bash
just graph-node-start
```

6. Deploy subgraph to graph-node (read more in [how to deploy subgraphs guide](./graph-node/README.md#deploy-subgraph-to-graph-node))
```bash
just deploy-subgraph <protocol_name>
```

7. Add protocol to [dev.json](./bens-server/config/dev.json) config and start `bens-server` connected to common database (read more in [how to start bens guide](./bens-server/README.md#to-start-locally))

```bash
just run-dev
```

8. Check that `bens-server` responses with valid domains. You can find swagger docs at [https://blockscout.github.io/swaggers/services/bens/main/index.html](https://blockscout.github.io/swaggers/services/bens/main/index.html)

9. Add your protocol to list of [supported domains](#current-supported-domains)

10. Update default config of BENS server for [production](./bens-server/config/prod.json) and [staging](./bens-server/config/staging.json)

11. Finally, create PR with:
* New directory inside `blockscout-ens/graph-node/subgraphs` with your subgraph code
* Updated BENS config
* Updated supported domains list
* Result of indexed data: proof that your indexed subgraph contains correct amount of domains, resolved_addresses and so on
* Result of indexed data: proof that your indexed subgraph contains correct amount of domains, resolved_addresses and so on

147 changes: 143 additions & 4 deletions blockscout-ens/graph-node/README.md
Original file line number Diff line number Diff line change
@@ -6,20 +6,159 @@ One can submit subgraph to `graph-node` -- actual code how to handle new events

## Start locally using docker-compose

1. Edit `docker-compose.yml` and change `ethereum` ENV variable of `graph-node` services to add your own network and RPC url.
1. You may need to add your custom network to `config.toml`

1. Start your own graph-node with docker-compose:
2. Start your own graph-node with docker-compose:

```bash
docker-compose up -d
```

1. Load small version of ens-rainbow
3. Load small version of ens-rainbow

```bash
./rainbow.small.sh
```

Or use [full ens-rainbow](https://github.com/graphprotocol/ens-rainbow/) dump if you want full domain name resolving

1. Read [subgraphs/README.md](./subgraphs/README.md) to build and deploy subgraph to graph-node

## Add your own subgraph

Read guide [How to add new subgraph](./subgraph-writer/README.md)


## Deploy subgraph to graph-node


### Convenient `deployer` script with `just`

1. Add your protocol to [deployer/config.json](./deployer/config.json)

2. Run deployer script to deploy to local graph-node:

```bash
just deploy-subgraph <protocol_name>
```

3. Run deployer script to deploy to remote graph-node:

```bash
just deploy-subgraph --prod <protocol_name>
```

### Manually with `yarn`

1. Initially:

```bash
cd subgraphs/<subgraph_directory>
yarn install
yarn codegen
yarn build
```

2. **[FOR BLOCKSCOUT TEAM]** Make sure you have access to graph, for example using port forwarding to staging graph-node:

```bash
kubectl port-forward -n graph-node svc/graph-node 8020:8020
```

Or you can run your own `graph-node` using docker: read [start locally](#start-locally-using-docker-compose)

3. Create subgraph on graph-node

```bash
yarn graph create --node http://127.0.0.1:8020 <subgraph_name>
```

4. Deploy subgraph to graph-node

```bash
yarn graph deploy --node http://127.0.0.1:8020 --ipfs http://127.0.0.1:5001 --network <network_name> --version-label 0.0.1 <subgraph_name>
```

### Check results

+ Connect to subgraph database and check current state of deployed subgraph:

```postgres
select deployment, failed, health, synced, latest_ethereum_block_number, fatal_error from subgraphs.subgraph_deployment;
select * from subgraphs.subgraph_error;
select name, resolved_address, expiry_date
from sgd1.domain
where label_name is not null and block_range @> 2147483647
order by created_at
limit 100;
```
> Note that we selected from custom schema called `sgd1`. This schema is created by `graph-node` and will be automatically incremented to `sgd2`, `sgd3`, etc.
+ Run `bens-server` API and send requests to check results of subgraph: read [bens-server docs](../../bens-server/README.md)
## SpaceID integration
Developing subgraph for protocol based on space-id contracts requires providing additional information.
SpaceID protocol has constant variable called `identifier` which unique describes protocol accross multiple chains.
This values is used during calculation of [namehash](https://docs.ens.domains/resolution/names#algorithm), therefore subgraph should know this value.
Actually blockscout-ens needs two values that can be calculated from `identifier`: `empty_label_hash` and `empty_label_hash`
+ `empty_label_hash` is basically hashed `identifier`
+ `base_node_hash` is hash of `base_node` plus `empty_label_hash`
### Obtaining `empty_label_hash` and `base_node_hash`
To obtain it, you need to make `eth_call` to Base contract (contract with NFT):
+ `mode-sepolia` example
```bash
BASE_NODE=mode \
RPC_URL=https://sepolia.mode.network \
CONTRACT=0xCa3a57e014937C29526De98e4A8A334a7D04792b \
python3 tools/fetch-space-id.py
OUTPUTS:
identifier: '0x00000397771a7e69f683e17e0a875fa64daac091518ba318ceef13579652bd79'
empty_label_hash: '0xea1eb1136f380e6643b69866632ce3b493100790c9c84416f2769d996a1c38b1'
base_node_hash: '0x9217c94fd014da21f5c43a1fcae4154a2bbfce43eb48bb33f7f6473c68ee16b6'
```
+ `mode-mainnet` example
```bash
RPC_URL=https://mainnet.mode.network \
CONTRACT=0x2ad86eeec513ac16804bb05310214c3fd496835b \
BASE_NODE=mode \
python3 tools/fetch-space-id.py
OUTPUTS:
identifier: '0x0000868b771a7e69f683e17e0a875fa64daac091518ba318ceef13579652bd79'
empty_label_hash: '0x2fd69f9e5bec9de9ebf3468dafc549eca0bc7d17dfbc09869c2cfc3997d5d038'
base_node_hash: '0x2f0e9a68fa134a18a7181045c3549d639665fe43df78e882d8adea865a4bb153'
```
### Using `empty_label_hash` and `base_node_hash`
1. `base_node_hash` for subgraph
Put `base_node_hash` (without `0x` prefix) inside `utils.ts`, for example:
```
export const BASE_NODE_HASH = "9217c94fd014da21f5c43a1fcae4154a2bbfce43eb48bb33f7f6473c68ee16b6"
```
Also don't forget to replace this value if you change network (from mainnet to testnet for example)
1. `empty_label_hash` for BENS
Put `empty_label_hash` in json configuration of BENS.
Use mainnet inside [prod.json](../../bens-server/config/prod.json) and testnet [staging.json](../../bens-server/config/staging.json)
8 changes: 5 additions & 3 deletions blockscout-ens/graph-node/subgraph-writer/README.md
Original file line number Diff line number Diff line change
@@ -10,6 +10,7 @@ You can take a look at that subgraph and understand structure of our project mor
1. Install python3 and install deps:

```bash
# running in this directory
just init
```

@@ -34,7 +35,7 @@ You can take a look at that subgraph and understand structure of our project mor
1. Move to recently created directory and run

```bash
just init && just codegen
yarn install && yarn codegen
```

In case of any error, adjust typescript code of subgraph. Also make sure subgraph handles events properly.
@@ -51,7 +52,8 @@ You can take a look at that subgraph and understand structure of our project mor
1. Now build subgraph code

```bash
just build
yarn build
```

1. Now you should run your subgraph by submitting it to graph-node: read [deploy subgraphs to graph-node](../subgraphs/README.md#deploy-subgraph-to-graph-node)
1. Now you should run your subgraph by submitting it to graph-node: read [deploy subgraphs to graph-node](../README.md#deploy-subgraph-to-graph-node)

Original file line number Diff line number Diff line change
@@ -3,15 +3,6 @@ ipfs_url := "http://127.0.0.1:5001"
network := "{{ cookiecutter.network }}"
name := "{{ cookiecutter.project_slug }}"
{% raw %}
init:
yarn install

codegen:
yarn codegen

build:
yarn build

create:
yarn graph create --node {{graph_node_url}} {{name}}

Loading