Gotchipz Go CLI Expert

Expert assistant for working with the Gotchipz repository - a Go CLI tool for interacting with testnet services including Pharos, Gotchipus, and ARC.

Repository Overview

This is a small Go CLI that interacts with several testnet services. The codebase follows a modular action-based architecture where each service gets its own action module.

**Core Architecture:**

Key Files and Their Roles

When working in this repository, prioritize understanding these files:

1. **main.go** - Program entry point, orchestrates action calls

2. **cfg/config.go** - Constants, endpoints, and addresses used across modules

3. **cfg/entity.go** - Shared structs (`ParamHub`, `PharosTask`, etc.)

4. **cfg/switcher.go** - `RpcHub` and `ClientService` for RPC client management

5. **cfg/act_*.go** - Action implementations per service (e.g., `act_pharoshub.go`, `act_gotchipus.go`)

6. **rpc.json** - RPC endpoints and metadata

7. **README.md** - Project description

Development Workflow

Building and Running

```bash

Build the project

go build ./...

Run the CLI

go run main.go

Run tests

go test ./...

```

Environment Setup

- `pharos_bear.txt` - Bearer token storage

- `pharos_last_check.txt` - Timestamp tracking

- `x_ids.txt` - ID tracking

- `addr_dummy.txt` - Address data

Code Patterns and Conventions

Action Module Pattern

All service integrations follow the `act_<service>.go` naming pattern:

RPC Client Management

**Key Pattern:**

```go

// RpcHub collects multiple ethclient.Client instances from rpc.json

// Switch between them using ClientService.SwitchRpc()

// Always use ClientService.GetCurrentClient() when calling the chain

```

**Important:** Avoid double-closing clients if reusing them across functions. Many functions call `param.Provider.Close()` or use `defer param.Provider.Close()`.

HTTP Request Pattern

Centralized HTTP pattern in `cfg/act_gotchipus.go`:

State Persistence

Uses plain text files for lightweight state:

Integration Points

External Dependencies

Heavy use of `github.com/ethereum/go-ethereum` packages:

**Rule:** Any Ethereum interaction changes must respect `ParamHub` and `ethclient` usage patterns.

External Services

Adding a New Service Action

Follow this recipe when adding a new service integration:

1. **Create action file:** `cfg/act_newservice.go` following existing `act_*.go` structure

2. **Use ParamHub:**

```go

// Create via ethclient and private key from .env

// Call NewClientService(param, rpcs) if RPC switching needed

```

3. **Reuse HTTP patterns:**

- Use `doRequest` for HTTP interactions

- Use `SaveBear`/`LoadBearToken` for JWT-like token caching

4. **Add tests:**

- Follow `cfg/act_pharoshub_test.go` naming convention

- Ensure tests work with `go test ./...`

Common Pitfalls

1. **Double-closing clients:** Many functions close `param.Provider` - avoid reusing closed clients

2. **Missing runtime files:** Code expects `.env`, `addr_dummy.txt`, `x_ids.txt` in working directory

3. **Network timeouts:** Functions use `context.WithTimeout` with short durations - test with realistic network latencies

4. **RPC switching:** Always use `ClientService.GetCurrentClient()` instead of direct client access

Questions to Clarify with Repo Owner

Instructions for AI Assistant

When helping with this repository:

1. **Read before suggesting:** Always inspect relevant action files before proposing changes

2. **Follow patterns:** Maintain consistency with existing `act_*.go` structure

3. **Respect ParamHub:** All Ethereum interactions should use `ParamHub` pattern

4. **Check file dependencies:** Verify required text files exist before running code

5. **Test network calls:** Consider network latency when working with timeouts

6. **Reuse utilities:** Use existing `doRequest`, token management, and RPC switching helpers

7. **Document new actions:** Follow existing documentation style when adding services

When user requests modifications: