Develop

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,4 +2,5 @@
 <!-- Please include a summary of the change and which issue is fixed. -->
 
 ## PR Target Branch
+
 - [ ] I am targeting the `develop` branch for non-release changes.

.github/copilot-instructions.md

@@ -0,0 +1,100 @@
+# TrueBlocks Core Development Instructions
+
+## Project Overview
+
+TrueBlocks is a Go-based blockchain data indexing system that provides fast, local access to Ethereum transaction data through the "Unchained Index". The project consists of:
+
+- **chifra**: Main CLI tool (`src/apps/chifra/`) built with Cobra framework
+- **SDK**: Multi-language bindings (Go, TypeScript, Python) in `sdk/`
+- **khedra**: Extension system for specialized indexing (`khedra/`)
+- **examples**: Integration examples demonstrating SDK usage (`examples/`)
+
+## Architecture Patterns
+
+**Command Structure**: Each chifra command follows the pattern:
+- Command definition in `src/apps/chifra/cmd/[command].go`
+- Internal logic in `src/apps/chifra/internal/[command]/`
+- Package-specific types in `src/apps/chifra/pkg/types/`
+
+**Data Flow**: RPC → Cache → Index → Output
+- RPC calls through `pkg/rpc/`
+- Binary cache system in `pkg/cache/`
+- Index operations in `pkg/index/`
+- Output formatting in `pkg/output/`
+
+**Base Types**: Core blockchain types in `pkg/base/`:
+- `base.Address` for Ethereum addresses
+- `base.Hash` for transaction/block hashes  
+- `base.Wei` for precise ETH calculations
+- `base.Timestamp` for block times
+
+## Development Workflows
+
+**Building**: Use CMake from `build/` directory or Go directly:
+```bash
+# Full build with CMake
+cd build && make
+# Go build only
+cd src/apps/chifra && go build
+```
+
+**Testing**: Multi-layer approach:
+- Unit tests: `go test ./...` in chifra directory
+- Integration tests: `scripts/test-all.sh` 
+- Golden file tests in `tests/gold/`
+- Set `TEST_MODE=true` for test-specific behavior
+
+**Code Generation**: 
+- SDK bindings auto-generated from chifra commands
+- Templates in `examples/templates/`
+- Use `scripts/go-mod-tidy.sh` for dependency management
+
+## Critical Conventions
+
+**Error Handling**: Always use TrueBlocks patterns:
+- `pkg/logger` for logging (not fmt.Print)
+- `pkg/validate` for input validation
+- Return structured errors, not bare strings
+
+**Configuration**: 
+- Config files in `~/.local/share/trueblocks/` or `~/Library/Application Support/TrueBlocks/`
+- Use `pkg/config` for settings access
+- Environment variables prefixed with `TB_`
+
+**Data Structures**:
+- Implement `String()` methods for custom types
+- Use `pkg/types` for shared data structures
+- Follow naming: `Simple[Type]` for basic structs, `[Type]` for full objects
+
+**Multi-Chain Support**:
+- Chain-specific configs in config directories
+- Use `base.KnownChain` constants
+- RPC endpoints configurable per chain
+
+## SDK Integration
+
+**Language Bindings**: 
+- Go SDK is primary (`sdk/*.go`)
+- TypeScript/Python generated from Go definitions
+- All SDKs call chifra binary under the hood
+
+**Examples Structure**:
+- Each example is self-contained with `go.mod`
+- Follow `examples/simple/` pattern for new examples
+- Include both programmatic and CLI usage
+
+## Common Pitfalls
+
+- **Don't** use `fmt.Print` - use `pkg/logger`
+- **Don't** hardcode chain IDs - use configuration
+- **Don't** bypass cache system - use `pkg/cache` for performance
+- **Don't** ignore `TEST_MODE` environment variable in test code
+- **Always** validate addresses with `base.IsValidAddress()`
+- **Always** handle Wei arithmetic with `base.Wei` type
+
+## Key Files to Reference
+
+- `src/apps/chifra/cmd/root.go` - CLI framework setup
+- `src/apps/chifra/pkg/base/types.go` - Core type definitions  
+- `examples/simple/main.go` - Basic SDK usage pattern
+- `scripts/test-all.sh` - Complete testing workflow

.github/workflows/build-and-test.yml

@@ -83,6 +83,7 @@ jobs:
           key: ${{ secrets.SSH_PRIVATE_KEY }}
           command_timeout: 40m
           script: |
+            set -e  # Exit on any error
             rm -rf testing/${{ github.sha }}
             mkdir -p testing/${{ github.sha }}
             mkdir -p test_results/${{ github.sha }}
@@ -92,6 +93,11 @@ jobs:
             git checkout ${{ github.head_ref }}
             git submodule update --init --recursive
             cd scripts
-            CONFIG_FILE=$HOME/trueBlocks.toml bash test-with-docker.sh ${{ github.repository }} ${{ github.sha }} ${{ github.head_ref }}
+            if CONFIG_FILE=$HOME/trueBlocks.toml bash test-with-docker.sh ${{ github.repository }} ${{ github.sha }} ${{ github.head_ref }}; then
+              echo "✅ Tests passed successfully"
+              echo "Results placed in /home/testuser/testing/${{ github.sha }}"
+            else
+              echo "❌ Tests failed"
+              exit 1
+            fi
             docker system prune -af --filter "until=1h"
-            echo "Results placed in /home/testuser/testing/${{ github.sha }}"

.gitignore

@@ -57,3 +57,4 @@ py-ext/dist/
 
 node_modules
 sdk/typescript/dist
+.claude/

.golangci.yml

@@ -1,58 +1,70 @@
-# ./.golangci.yml
+version: "2"
 run:
-  timeout: 5m
   modules-download-mode: readonly
-
 linters:
+  default: none
   enable:
-    - gofmt # enforces formatting
-    - revive # custom rules like unused-parameter
-    - errcheck # unchecked errors
-    - staticcheck # static analysis
-    - unused # unused code
-    - misspell # catches typos
-    - ineffassign # ineffective assignments
-    - prealloc # suggests pre-allocation
-    # - goconst # finds repeated strings for consts
-    # - gosec # basic security checks
-  disable-all: true
-
-linters-settings:
-  gofmt:
-    simplify: true
-  revive:
+    - errcheck
+    - ineffassign
+    - misspell
+    - prealloc
+    - revive
+    - staticcheck
+    - unused
+  settings:
+    revive:
+      rules:
+        - name: unused-parameter
+          severity: warning
+    staticcheck:
+      checks:
+        - all
+        - -QF1008 # could remove embedded field "Xxx" from selector
+        - -QF1006 # could lift into loop condition
+        - -ST1003 # should not use MixedCaps in package name
+        - -ST1016 # methods on the same type should have the same receiver name
+  exclusions:
+    generated: lax
+    presets:
+      - comments
+      - common-false-positives
+      - legacy
+      - std-error-handling
     rules:
-      # - name: var-naming
-      #   severity: warning
-      - name: unused-parameter
-        severity: warning
-  goconst:
-    min-len: 3 # Minimum length of repeated string
-    min-occurrences: 3 # Minimum times it must appear
-  gosec:
-    excludes:
-      - G104 # Ignore some noisy security rules (e.g., error handling)
-
-issues:
-  exclude-rules:
-    - path: src/apps/chifra/internal/scrape/handle_show.go
-      linters:
-        - ineffassign
-    - path: src/apps/chifra/internal/[^/]+/options\.go
-      linters:
-        - ineffassign
-    - path: src/apps/chifra/pkg/types/types_
-      linters:
-        - ineffassign
-    - path: _test\.go
-      linters:
-        - gofmt
-        - revive
-        - errcheck
-        - staticcheck
-        - unused
-        - misspell
-        - goconst
-        - ineffassign
-        - prealloc
-        - gosec
+      - linters:
+          - ineffassign
+        path: src/apps/chifra/internal/scrape/handle_show.go
+      - linters:
+          - ineffassign
+        path: src/apps/chifra/internal/[^/]+/options\.go
+      - linters:
+          - ineffassign
+        path: src/apps/chifra/pkg/types/types_
+      - linters:
+          - errcheck
+          - goconst
+          - gosec
+          - ineffassign
+          - misspell
+          - prealloc
+          - revive
+          - staticcheck
+          - unused
+        path: _test\.go
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+formatters:
+  enable:
+    - gofmt
+  settings:
+    gofmt:
+      simplify: true
+  exclusions:
+    generated: lax
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+      - _test\.go

.markdownlint.yaml

@@ -1,5 +1,21 @@
+MD001: false
+MD007: false
+MD009: false
+MD010: false
 MD013: false
+MD022: false
+MD024: false
+MD025: false
+MD026: false
+MD029: false
+MD030: false
+MD031: false
+MD032: false
 MD033: false
 MD036: false
+MD040: false
 MD041: false
-MD024: false
+MD046: false
+MD047: false
+MD052: false
+MD058: false

BLOCK_TIME_CONFIG.md

@@ -0,0 +1,80 @@
+# Block Time Configuration
+
+This document describes the block time configuration system introduced to fix issue #3974 where timestamps on Optimism (and other chains) were incorrect due to hardcoded Ethereum mainnet block times.
+
+## Problem
+
+Previously, TrueBlocks used hardcoded values (13 or 13.3 seconds) for block time calculations across all chains. This caused incorrect timestamp-to-block conversions for chains with different block times like Optimism (2 seconds), Polygon (2 seconds), etc.
+
+## Solution
+
+### 1. Configuration Structure
+
+Added a `blockTime` field to the `ChainGroup` structure in `pkg/configtypes/chain_group.go`:
+
+```go
+type ChainGroup struct {
+    // ... existing fields ...
+    BlockTime float64 `json:"blockTime" toml:"blockTime,omitempty"`
+    // ... rest of fields ...
+}
+```
+
+### 2. Block Time Helper
+
+Created `pkg/config/blocktime.go` with:
+- Default block times for known chains
+- `GetBlockTime(chain string)` function that:
+  - First checks configuration file
+  - Falls back to known defaults
+  - Uses Ethereum mainnet (13s) as ultimate fallback
+
+### 3. Updated Calculations
+
+Updated hardcoded values in:
+- `pkg/tslib/tsdb.go`: Line 100
+- `pkg/identifiers/resolve.go`: Line 201
+
+Both now use `config.GetBlockTime(chain)` instead of hardcoded values.
+
+### 4. Configuration
+
+Add block times to your `trueBlocks.toml`:
+
+```toml
+[chains.mainnet]
+blockTime = 13.0
+
+[chains.optimism]
+blockTime = 2.0
+
+[chains.polygon]
+blockTime = 2.0
+```
+
+## Default Block Times
+
+| Chain | Block Time (seconds) |
+|-------|---------------------|
+| Ethereum Mainnet | 13.0 |
+| Optimism | 2.0 |
+| Polygon | 2.0 |
+| BSC | 3.0 |
+| Gnosis | 5.0 |
+| Arbitrum | 0.25 |
+| Base | 2.0 |
+| Avalanche | 2.0 |
+| zkSync Era | 1.0 |
+
+See `pkg/config/blocktime.go` for the complete list.
+
+## Testing
+
+Run tests with:
+```bash
+go test ./pkg/config/blocktime_test.go
+```
+
+## Migration
+
+No action required for existing installations. The system will use defaults if `blockTime` is not configured.

CHANGES.md

@@ -2,6 +2,8 @@
 
 This file details changes made to TrueBlocks over time. All version prior to version 3.0.0 are now no longer supported.
 
+## v6.0.0 - Coming soon...
+
 ## v5.0.0 - All About Them Recons - Lancaster (2025/03/28)
 
 **Summary**

README.md

@@ -130,7 +130,7 @@ Our [official docker version](https://github.com/TrueBlocks/trueblocks-docker) i
 
 ## Documentation
 
-The documenation is stored in the ./docs folder of this repo. See our website for the [best available documentation](https://trueblocks.io/).
+The documentation is stored in the ./docs folder of this repo. See our website for the [best available documentation](https://trueblocks.io/).
 
 ## Linting