Merge branch 'andrius/param-refactoring' into 'main'

refactor: consolidate log_range and rename binary/module for v2

See merge request flarenetwork/FSP/flare-system-c-chain-indexer!83

Author: adg-flare

CHANGELOG.md

@@ -40,9 +40,17 @@ and this project adheres to
 
 - Repository structure refactored under `cmd/` and `internal/` to follow
   conventional Go layout. The runnable binary moved to `./cmd/indexer`.
+- **Binary renamed** to `flare-cchain-indexer` (previously
+  `flare_cchain_indexer` in the Dockerfile / `flare-ftso-indexer` in legacy
+  build snippets). Deployment scripts, container `command:` entries, and any
+  process supervisors that reference the binary by name need to be updated.
+- **Go module path renamed** from `flare-ftso-indexer` to
+  `github.com/flare-foundation/flare-system-c-chain-indexer`. The indexer is
+  shipped as a binary, but any out-of-tree imports must be updated.
 - Block-by-timestamp lookup uses heuristics to narrow the search window before
   binary search, avoiding requests for very old blocks when running against
   RPC nodes with limited history.
+- Minimum Go toolchain version raised to 1.24.
 
 
 ## \[[v1.1.2](https://github.com/flare-foundation/flare-system-c-chain-indexer/tree/v1.1.2)\] - 2025-11-03

Dockerfile

@@ -11,7 +11,7 @@ RUN go mod download
 COPY . ./
 
 # Build the applications
-RUN go build -o /app/flare_cchain_indexer ./cmd/indexer
+RUN go build -o /app/flare-cchain-indexer ./cmd/indexer
 
 FROM debian:trixie-slim@sha256:cedb1ef40439206b673ee8b33a46a03a0c9fa90bf3732f54704f99cb061d2c5a AS execution
 
@@ -23,6 +23,6 @@ RUN apt-get update \
 
 WORKDIR /app
 
-COPY --from=builder /app/flare_cchain_indexer .
+COPY --from=builder /app/flare-cchain-indexer .
 
-CMD ["./flare_cchain_indexer"]
+CMD ["./flare-cchain-indexer"]

README.md

@@ -28,7 +28,7 @@ docker-compose.yaml file for automatic deployment of a database).
 
 ### Configuration
 
-The configuration is read from a `toml` file. Config file can be specified using the command line parameter `--config`, e.g., `./flare-ftso-indexer --config config.toml`.
+The configuration is read from a `toml` file. Config file can be specified using the command line parameter `--config`, e.g., `./flare-cchain-indexer --config config.toml`.
 The default config file name is `config.toml`.
 Use [`config.example.toml`](config.example.toml) as the single config template. It includes full mode/indexer/db/chain/logger/timeout examples and comments.
 
@@ -37,6 +37,14 @@ Use [`config.example.toml`](config.example.toml) as the single config template.
 - `indexer.mode = "fsp"`: use this when running as part of the FSP provider stack. Required FSP transactions/logs are hardcoded and auto-applied, so you do not need to specify `[[indexer.collect_transactions]]` or `[[indexer.collect_logs]]` in config (you can still add extra entries; they are merged and deduplicated). FSP startup also does selective indexing for required reward-epoch metadata windows instead of blindly indexing full historical ranges, which makes startup significantly faster. In this mode, `indexer.start_index` and `db.history_drop` are ignored; retention is derived from `indexer.history_epochs`.
 - `indexer.mode = "full"`: use this for a generic C-chain indexer. In this mode you should define what to index via `[[indexer.collect_transactions]]` and `[[indexer.collect_logs]]`.
 
+#### Contract addressing
+
+Contracts in `[[indexer.collect_transactions]]` and `[[indexer.collect_logs]]` can be specified either by `contract_address = "0x..."` or by `contract_name = "FlareSystemsManager"`. When a name is provided, the indexer resolves it to an address at startup via the on-chain ContractRegistry, so addresses that differ across networks (or change between deployments) do not need to be hardcoded in config. FSP mode's built-in collectors all use name-based resolution.
+
+#### Startup and history (full mode)
+
+The behavior described in this section applies to **full mode** only. FSP mode derives its start block and retention from `indexer.history_epochs`, and ignores both `indexer.start_index` and `db.history_drop`.
+
 If the C chain indexer has been previously run and there is existing data in the database,
 subsequent runs will resume indexing from after the last indexed block. Only when starting with an
 empty database will the indexer have to decide where to start. Normally this will be based on the
@@ -71,8 +79,8 @@ go run ./cmd/indexer --config config.toml
 or build and run the binaries with
 
 ```bash
-go build -o flare-ftso-indexer ./cmd/indexer
-./flare-ftso-indexer --config config.toml
+go build -o flare-cchain-indexer ./cmd/indexer
+./flare-cchain-indexer --config config.toml
 ```
 
 ### Health endpoint
@@ -113,7 +121,7 @@ go tool cover -html=coverage.out
 
 ### Benchmarks
 
-File `benchmarks/songbird_test.go` contains a benchmark test for indexing the FTSO protocol on the Songbird network. It processes 10,000 blocks and analyzes them. The test configuration is specified in `benchmarks/config_banchmark.toml`. To run the benchmark (replacing 10x with any desired number of repetitions), use:
+File `benchmarks/songbird_test.go` contains a benchmark test for indexing the FTSO protocol on the Songbird network. It processes 10,000 blocks and analyzes them. The test configuration is specified in `benchmarks/config_benchmark.toml`. To run the benchmark (replacing 10x with any desired number of repetitions), use:
 
 ```bash
 go test -benchmem -run=^$ -benchtime 10x -bench ^BenchmarkBlockRequests$ ./benchmarks

benchmarks/config_banchmark.toml benchmarks/config_benchmark.tomlbenchmarks/config_banchmark.toml renamed to benchmarks/config_benchmark.toml

@@ -11,7 +11,7 @@ drop_table_at_start = true
 
 [logger]
 level = "INFO"
-file = "../logs/flare-ftso-indexer_log"
+file = "../logs/flare-cchain-indexer.log"
 console = true
 
 [chain]

benchmarks/songbird_test.go

@@ -2,13 +2,14 @@ package benchmarks
 
 import (
 	"context"
-	"flare-ftso-indexer/internal/chain"
-	"flare-ftso-indexer/internal/config"
-	"flare-ftso-indexer/internal/contracts"
-	"flare-ftso-indexer/internal/core"
-	"flare-ftso-indexer/internal/database"
 	"testing"
 
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/chain"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/config"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/contracts"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/core"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/database"
+
 	"github.com/BurntSushi/toml"
 	"github.com/flare-foundation/go-flare-common/pkg/logger"
 )
@@ -23,7 +24,7 @@ func BenchmarkBlockRequests(b *testing.B) {
 	tCfg := benchmarksConfig{}
 	tCfg.Indexer.Confirmations = 1
 	tCfg.Chain.ChainType = 1
-	_, err := toml.DecodeFile("config_banchmark.toml", &tCfg)
+	_, err := toml.DecodeFile("config_benchmark.toml", &tCfg)
 	if err != nil {
 		logger.Fatalf("Config error: %s", err)
 	}

cmd/indexer/main.go

@@ -3,21 +3,22 @@ package main
 import (
 	"context"
 	"flag"
-	"flare-ftso-indexer/internal/boff"
-	"flare-ftso-indexer/internal/chain"
-	"flare-ftso-indexer/internal/config"
-	"flare-ftso-indexer/internal/contracts"
-	"flare-ftso-indexer/internal/core"
-	"flare-ftso-indexer/internal/database"
-	"flare-ftso-indexer/internal/fsp"
-	"flare-ftso-indexer/internal/health"
-	"flare-ftso-indexer/internal/ready"
 	"fmt"
 	"os"
 	"os/signal"
 	"syscall"
 	"time"
 
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/boff"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/chain"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/config"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/contracts"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/core"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/database"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/fsp"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/health"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/ready"
+
 	"github.com/flare-foundation/go-flare-common/pkg/logger"
 	"github.com/pkg/errors"
 	"gorm.io/gorm"

cmd/indexer/main_test.go

@@ -8,11 +8,11 @@ import (
 	"testing"
 	"time"
 
-	"flare-ftso-indexer/internal/chain"
-	"flare-ftso-indexer/internal/config"
-	"flare-ftso-indexer/internal/contracts"
-	"flare-ftso-indexer/internal/core"
-	"flare-ftso-indexer/internal/database"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/chain"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/config"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/contracts"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/core"
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/database"
 
 	"github.com/BurntSushi/toml"
 	"github.com/bradleyjkemp/cupaloy/v2"

config.example.toml

@@ -5,12 +5,10 @@ stop_index = 0 # stop block; set 0 to index indefinitely
 history_epochs = 0 # FSP mode only: 0=last 2 hours, >0=number of reward epochs to keep/index from
 num_parallel_req = 100 # number of parallel requests to the chain
 batch_size = 1000 # the number of blocks that will be pushed to a database in a batch (should be divisible by num_parallel_req)
-log_range = 10 # the size of the interval of blocks used to request logs in each request; suggested value is log_range = batch_size / num_parallel_req; note that a blockchain node might have an upper bound on this
+log_range = 1024 # max blocks per eth_getLogs request; set to your RPC's getLogs cap (typically 100-10000)
 new_block_check_millis = 1000 # interval for checking for new blocks
 confirmations = 1 # number of confirmations for latest block queries
 no_new_blocks_delay_warning = 60 # max allowed delay between consecutive processed blocks before warning; 0 disables warning
-fsp_tx_lookback_seconds = 7200 # FSP mode startup tx lookback window (default 2h)
-fsp_log_filter_range = 1024 # FSP mode block range per FilterLogs request during metadata backfill
 
 [[indexer.collect_transactions]]
 contract_address = "0x2cA6571Daa15ce734Bbd0Bf27D5C9D16787fc33f" # example target contract; alternatively use contract_name
@@ -24,7 +22,7 @@ topic = "undefined" # topic0 filter; use "undefined" to index all events from th
 
 [logger]
 level = "INFO"
-file = "./logs/flare-ftso-indexer.log"
+file = "./logs/flare-cchain-indexer.log"
 console = true
 
 [chain]

go.mod

@@ -1,6 +1,6 @@
-module flare-ftso-indexer
+module github.com/flare-foundation/flare-system-c-chain-indexer
 
-go 1.23.0
+go 1.24.0
 
 require (
 	github.com/BurntSushi/toml v1.5.0

internal/boff/backoff.go

@@ -4,9 +4,10 @@ package boff
 
 import (
 	"context"
-	"flare-ftso-indexer/internal/config"
 	"time"
 
+	"github.com/flare-foundation/flare-system-c-chain-indexer/internal/config"
+
 	"github.com/cenkalti/backoff/v5"
 	"github.com/flare-foundation/go-flare-common/pkg/logger"
 )