You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- README.md: Node v16→v20, src/types described as auto-generated,
added Makefile targets and docs/typeChanges.md to project layout,
restored architecture diagram
- docs/readme.md: added links to typeChanges.md and release_process.md
- docs/development.md: added sections for type generation workflow,
GraphQL schema modification, and DB reset; restored log screenshots
- docs/production.md: documented all env vars for indexer and
processor, added architecture overview, improved resync section
- docs/release_process.md: documented make version-bump, fixed chart
paths (indexer/chart.yaml→indexer/chart/Chart.yaml), added CI
auto-publish note
- indexer/readme.md: documented START_HEIGHT, reformatted container
list as table
- indexer/development.md: fixed title (types.json→typesBundle.json),
clarified typesBundle is frozen with link to typeChanges.md
- indexer/chart/README.md: fixed typo (missing space in helm command)
- processor-chart/README.md: fixed wrong path
(cd tfchain/graphql/processor-chart→cd processor-chart)
- scripts/readme.md: fixed typo (Sripts→Scripts), fixed wrong script
name (restart-db.sh→reset-db.sh), added missing scripts
(seed-versions.sh, merge-versions.js, init-db.sh)
Refs: #119, #120
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1.**Indexer (archive)** — ingests raw blocks from a TFChain node into CockroachDB. Provides a GraphQL gateway for the processor to query block data.
14
+
2.**Processor + Query Node** — reads events from the indexer, maps them to domain entities (nodes, farms, contracts, etc.), stores in PostgreSQL, and serves the public GraphQL API.
|`START_HEIGHT`| Block height to start ingesting from. `0` = genesis (full history). Set higher only for testing or partial deployments — the processor will miss events before this height. |`0`|
16
26
17
27
```bash
18
28
cd indexer
19
29
docker-compose up -d
20
30
```
21
31
22
-
### Processor
32
+
See [indexer/readme.md](../indexer/readme.md) for details on the indexer stack containers.
33
+
34
+
### 2. Processor + Query Node
23
35
24
-
Configure the `.env`file in the root of this repository.
36
+
Configure `.env` in the project root:
25
37
26
-
Set the `WS_URL` to a tfchain network url.
38
+
| Variable | Description | Default |
39
+
|----------|-------------|---------|
40
+
|`DB_NAME`| PostgreSQL database name |`tfgrid-graphql`|
|`WS_URL`| TFChain node WebSocket URL (used for RPC calls) |`ws://localhost:9944`|
46
+
|`TYPEORM_LOGGING`| TypeORM log level |`error`|
27
47
28
48
```bash
29
49
docker-compose up -d
30
50
```
31
51
32
-
Now the graphql endpoint is available at `http://localhost:4000/graphql`
52
+
The GraphQL endpoint is now available at `http://localhost:4000/graphql`
33
53
34
-
## Releasing
54
+
## Reprocessing
35
55
36
-
See [release process](./release_process.md)
56
+
If a mapping bug is fixed and data needs remapping, reset the processor database and reindex:
37
57
38
-
## Notes
58
+
```bash
59
+
docker-compose down processor query-node
60
+
./scripts/reset-db.sh
61
+
docker-compose up -d
62
+
```
39
63
40
-
### Reprocessing of indexer data
64
+
This drops and recreates the processor's PostgreSQL database and reindexes from block 0 against the existing indexer data. The indexer does not need to be restarted — it stores raw blocks independently.
41
65
42
-
Reprocessing of indexer data (running the processor) would be usefull in situation where bugs are found and the data that is mapped would need remapping. This can be done by deleting the processor data and running it from 0 again with the code changes.
66
+
See [typeChanges.md](./typeChanges.md) for more detail on when a resync is needed.
1. Update the version in `indexer/chart.yaml` and `processor-chart/chart.yaml`
6
-
2. Update the version `package.json` and `package-lock.json` (by doing `npm install` or `yarn`)
7
-
3. Commit and these changes and tag the commit with the new version (e.g. `v0.0.1`)
8
-
4. Create a release on github release page from the tag. The release title should be the version number and the release description should contain the changelog.
5
+
The Makefile automates version bumping across `package.json` and both Helm charts:
6
+
7
+
```bash
8
+
make version-bump type=patch # 2.12.3 → 2.12.4
9
+
make version-bump type=minor # 2.12.3 → 2.13.0
10
+
make version-bump type=major # 2.12.3 → 3.0.0
11
+
```
12
+
13
+
This will:
14
+
1. Checkout the default branch and pull latest
15
+
2. Create a new branch `{default-branch}-bump-version-to-{version}`
16
+
3. Update versions in `package.json`, `indexer/chart/Chart.yaml`, and `processor-chart/Chart.yaml`
17
+
4. Commit the changes
18
+
19
+
Then create a PR, get it merged, and tag the release.
20
+
21
+
## Manual Version Bump
22
+
23
+
If you prefer to do it manually:
24
+
25
+
1. Update the version in `package.json`
26
+
2. Update `appVersion` in `indexer/chart/Chart.yaml` and `processor-chart/Chart.yaml`
27
+
3. Commit and tag the commit with the new version (e.g., `v2.13.0`)
28
+
29
+
## Creating a Release
30
+
31
+
1. Create a release on the GitHub releases page from the tag
32
+
2. The release title should be the version number
33
+
3. The release description should contain the changelog
34
+
4. The `publish_container_images.yml` workflow will automatically build and push container images on tagged releases
Create PersistentVolumeClaims for the database if wanted and reference the name in your values file in the `volume.existingpersistentVolumeClaim` property.
5
+
Create PersistentVolumeClaims for the database if needed and reference the name in your values file in the `volume.existingpersistentVolumeClaim` property.
If the indexer cannot reach the database, you can set `db_url` to the db-service cluster ip.
11
+
If the indexer cannot reach the database, you can set `db_url` to the db-service cluster IP:
12
12
13
13
```sh
14
14
kubectl get svc
15
15
```
16
16
17
-
NOTE: take note of the IP assigned the db-service. Use this IP in `values.yaml` for the db_endpoint, ws_endpoint and indexer_status_service_url. Until DNS resolution works you can update these via 'helm upgrade'.
17
+
Take note of the IP assigned to the db-service. Use this IP in `values.yaml` for `db_endpoint`, `ws_endpoint`, and `indexer_status_service_url`. You can update these via `helm upgrade` if the IPs change.
When the typesBundle.json file has been modified, it needs to be updated in the helm chart as well.
5
+
The `typesBundle.json` file maps Substrate custom types for pre-V14 metadata (specVersions before ~v100). This file is **frozen** — TFChain now uses Polkadot SDK v1.1.0 with V14+ self-describing metadata, so new runtime versions do not require changes to this file.
6
+
7
+
See [docs/typeChanges.md](../docs/typeChanges.md#notes-on-typesbundlejson) for details.
8
+
9
+
## Updating the Helm Chart ConfigMap
10
+
11
+
If `typesBundle.json` ever needs updating (unlikely — only for newly discovered pre-V14 type gaps), regenerate the Helm chart configmap:
0 commit comments