Initial CAC3 explorer — design doc, license, config schema.
This is a docs-only seed. Tomorrow's session will add the actual Go source: main.go, internal/rpc/client.go (JSON-RPC + cookie auth), internal/chain/, internal/explorer/ (handlers), and internal/view/ (templates + static assets, embed.FS). Until then this commit gives the repo its shape: README with the full design, config example with all knobs, MIT license to match the chain, and a .gitignore for Go build artifacts.
This commit is contained in:
Sami Ahmed
+31
@@ -0,0 +1,31 @@
|
|||||||
|
# Go
|
||||||
|
/bin/
|
||||||
|
/dist/
|
||||||
|
*.exe
|
||||||
|
*.test
|
||||||
|
*.out
|
||||||
|
coverage.txt
|
||||||
|
*.prof
|
||||||
|
|
||||||
|
# Local config / secrets
|
||||||
|
.env
|
||||||
|
config.local.yaml
|
||||||
|
*.cookie
|
||||||
|
|
||||||
|
# Editor / OS
|
||||||
|
.DS_Store
|
||||||
|
.idea/
|
||||||
|
.vscode/
|
||||||
|
*.swp
|
||||||
|
*~
|
||||||
|
|
||||||
|
# Build cache
|
||||||
|
/tmp/
|
||||||
|
/cac3-explorer
|
||||||
|
/cac3-explorer-*
|
||||||
|
|
||||||
|
# Go modules (commit if not vendored; comment out if vendoring)
|
||||||
|
# vendor/
|
||||||
|
|
||||||
|
# Tailwind / static build cache
|
||||||
|
/static/css/.tailwind-cache/
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2026 Sami Ahmed
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
@@ -0,0 +1,179 @@
|
|||||||
|
# CAC3 Explorer
|
||||||
|
|
||||||
|
A Go single-binary block explorer for [CAC3 (Californiacoin3)](https://github.com/SamiAhmed7777/cac3).
|
||||||
|
Reads from a running `cac3d` node over its JSON-RPC interface (Bitcoin Core 0.18 style — cookie auth).
|
||||||
|
|
||||||
|
## What it shows
|
||||||
|
|
||||||
|
- **Home / chain tip** — current height, best block hash, difficulty, network hashrate, mempool size, last 10 blocks
|
||||||
|
- **Block detail** — by height or hash; full header, transactions, next/prev navigation
|
||||||
|
- **Transaction detail** — by txid; inputs/outputs with script-decoded addresses, value, confirmations
|
||||||
|
- **Address detail** — balance, total received/sent, UTXO list, recent tx history
|
||||||
|
- **Mempool** — current tx pool with fee/sat-per-byte sort
|
||||||
|
|
||||||
|
## Why Go
|
||||||
|
|
||||||
|
- One statically-linked binary — no runtime, no node_modules, no Python deps
|
||||||
|
- Cold start ~30ms, idle RSS ~15MB
|
||||||
|
- Embeds templates + static assets via `embed.FS` — single artifact deploy
|
||||||
|
- Native HTTP/2, easy `systemd` integration, fits the same deployment shape as DashCaddy / Triangles
|
||||||
|
|
||||||
|
## Quick start
|
||||||
|
|
||||||
|
### 1. Build
|
||||||
|
|
||||||
|
```bash
|
||||||
|
go build -ldflags="-s -w" -o cac3-explorer .
|
||||||
|
# or with a version stamp
|
||||||
|
go build -ldflags="-s -w -X main.Version=$(git describe --tags --always)" -o cac3-explorer .
|
||||||
|
```
|
||||||
|
|
||||||
|
Static binary, no glibc dep, runs anywhere.
|
||||||
|
|
||||||
|
### 2. Configure
|
||||||
|
|
||||||
|
The explorer reads config from (in priority order):
|
||||||
|
1. Flags (`--rpc-url`, `--cookie-path`, `--listen`, etc.)
|
||||||
|
2. Env vars (`CAC3_RPC_URL`, `CAC3_COOKIE_PATH`, `CAC3_LISTEN`, …)
|
||||||
|
3. `config.yaml` in the working directory
|
||||||
|
|
||||||
|
Example `config.yaml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
listen: "0.0.0.0:8080"
|
||||||
|
rpc:
|
||||||
|
url: "http://127.0.0.1:8332"
|
||||||
|
cookie_path: "/var/lib/cac3/.cookie"
|
||||||
|
# OR static creds (less secure, but useful for testing):
|
||||||
|
# user: "cac3rpc"
|
||||||
|
# pass: "changeme"
|
||||||
|
timeout: "10s"
|
||||||
|
|
||||||
|
chain:
|
||||||
|
name: "CAC3 Mainnet"
|
||||||
|
ticker: "CAC3"
|
||||||
|
# site URL used in <link rel="canonical"> / OG tags
|
||||||
|
site_url: "https://explorer.cac3.example"
|
||||||
|
|
||||||
|
# Address-link overrides — point these at your public node, block explorers, etc.
|
||||||
|
links:
|
||||||
|
# tx / address / block pages can deep-link to external tools if set
|
||||||
|
# wallet: "https://wallet.cac3.example"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./cac3-explorer --config config.yaml
|
||||||
|
# or fully env-var driven
|
||||||
|
CAC3_RPC_URL=http://127.0.0.1:8332 \
|
||||||
|
CAC3_COOKIE_PATH=/var/lib/cac3/.cookie \
|
||||||
|
CAC3_LISTEN=0.0.0.0:8080 \
|
||||||
|
./cac3-explorer
|
||||||
|
```
|
||||||
|
|
||||||
|
Open http://localhost:8080.
|
||||||
|
|
||||||
|
### 4. systemd (optional)
|
||||||
|
|
||||||
|
```ini
|
||||||
|
# /etc/systemd/system/cac3-explorer.service
|
||||||
|
[Unit]
|
||||||
|
Description=CAC3 Block Explorer
|
||||||
|
After=network.target cac3d.service
|
||||||
|
Wants=cac3d.service
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
User=cac3-explorer
|
||||||
|
Group=cac3-explorer
|
||||||
|
WorkingDirectory=/opt/cac3-explorer
|
||||||
|
ExecStart=/opt/cac3-explorer/cac3-explorer --config /etc/cac3-explorer/config.yaml
|
||||||
|
Restart=on-failure
|
||||||
|
RestartSec=5s
|
||||||
|
NoNewPrivileges=true
|
||||||
|
ProtectSystem=strict
|
||||||
|
ReadWritePaths=/var/log/cac3-explorer
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=multi-user.target
|
||||||
|
```
|
||||||
|
|
||||||
|
## RPC surface used
|
||||||
|
|
||||||
|
The explorer only needs a **non-wallet** `cac3d` node (no `wallet.dat` required, no signing keys).
|
||||||
|
Methods called:
|
||||||
|
|
||||||
|
| Method | Used for |
|
||||||
|
|---|---|
|
||||||
|
| `getblockchaininfo` | tip, difficulty, chainwork |
|
||||||
|
| `getnetworkinfo` | protocol version, connections |
|
||||||
|
| `getmininginfo` | hashrate, blocks |
|
||||||
|
| `getmempoolinfo` | mempool size, bytes |
|
||||||
|
| `getrawmempool` | mempool txid list |
|
||||||
|
| `getblockhash` | height → hash |
|
||||||
|
| `getblock` | block header + tx list (verbose=1) |
|
||||||
|
| `getblockheader` | header only |
|
||||||
|
| `getrawtransaction` | tx hex by txid |
|
||||||
|
| `decoderawtransaction` | decode inputs/outputs |
|
||||||
|
| `gettxoutsetinfo` | total supply stats |
|
||||||
|
| `getconnectioncount` | peer count |
|
||||||
|
| `getdifficulty` | current difficulty (decimal) |
|
||||||
|
| `listsinceblock` | recent wallet-scoped activity (only if `--show-wallet` enabled) |
|
||||||
|
|
||||||
|
No `sendtoaddress`, no signing, no key access. **Safe to expose the RPC port on a private interface** (or behind SSH tunnel) — the explorer's only attack surface is the read path.
|
||||||
|
|
||||||
|
## Repo layout
|
||||||
|
|
||||||
|
```
|
||||||
|
.
|
||||||
|
├── main.go # entrypoint, config, signal handling
|
||||||
|
├── internal/
|
||||||
|
│ ├── rpc/ # cac3d JSON-RPC client + cookie auth
|
||||||
|
│ │ ├── client.go
|
||||||
|
│ │ ├── auth.go # cookie + userpass
|
||||||
|
│ │ └── types.go # raw RPC types
|
||||||
|
│ ├── chain/ # domain types (Block, Tx, Address, …)
|
||||||
|
│ │ └── types.go
|
||||||
|
│ ├── explorer/ # handlers
|
||||||
|
│ │ ├── home.go
|
||||||
|
│ │ ├── block.go
|
||||||
|
│ │ ├── tx.go
|
||||||
|
│ │ ├── address.go
|
||||||
|
│ │ └── mempool.go
|
||||||
|
│ └── view/ # templates + render
|
||||||
|
│ ├── templates/ # html/template files (embed.FS)
|
||||||
|
│ └── static/ # css, js, favicon (embed.FS)
|
||||||
|
├── config.example.yaml
|
||||||
|
├── go.mod
|
||||||
|
├── go.sum
|
||||||
|
├── LICENSE # MIT, matches the chain license
|
||||||
|
└── README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Security notes
|
||||||
|
|
||||||
|
- **Cookie auth is preferred** — `cac3d` rotates `.cookie` on every restart. Re-read on every request (cheap, file is ~1KB).
|
||||||
|
- The explorer is **read-only**. It never sends `sendtoaddress` / `signrawtransaction` / `walletlock`. To prove this, search the source for those method names — they should not appear.
|
||||||
|
- Do not expose `cac3d`'s RPC port to the public internet. Bind it to `127.0.0.1` or a tailnet IP and let the explorer be the only public entry point.
|
||||||
|
- The explorer binds to whatever `--listen` says. Use a reverse proxy (Caddy / nginx) for TLS, rate limiting, and a real domain.
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# run with hot-reload (needs `air` or similar; not required)
|
||||||
|
go run .
|
||||||
|
|
||||||
|
# test
|
||||||
|
go test ./...
|
||||||
|
|
||||||
|
# vet / lint
|
||||||
|
go vet ./...
|
||||||
|
staticcheck ./... # if installed
|
||||||
|
```
|
||||||
|
|
||||||
|
The first request after `cac3d` start will be slow (RPC cold cache). Subsequent requests are <50ms for blocks, <200ms for address histories.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT — see [LICENSE](LICENSE). This explorer is a separate project from the CAC3 chain code; it only depends on `cac3d`'s documented JSON-RPC interface.
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
# CAC3 Explorer — example config
|
||||||
|
# Copy to config.yaml and edit, or override via flags / env vars.
|
||||||
|
|
||||||
|
listen: "0.0.0.0:8080"
|
||||||
|
|
||||||
|
rpc:
|
||||||
|
# Bitcoin Core 0.18 / cac3d JSON-RPC endpoint
|
||||||
|
url: "http://127.0.0.1:8332"
|
||||||
|
# Path to cac3d's .cookie file (preferred — auto-rotated on daemon restart).
|
||||||
|
cookie_path: "/var/lib/cac3/.cookie"
|
||||||
|
# OR static creds (less secure, but useful for tests):
|
||||||
|
# user: "cac3rpc"
|
||||||
|
# pass: "changeme"
|
||||||
|
timeout: "10s"
|
||||||
|
# How often to refresh the cookie file from disk. cac3d only writes it on
|
||||||
|
# startup, so this is mostly a safety net.
|
||||||
|
cookie_refresh: "30s"
|
||||||
|
|
||||||
|
chain:
|
||||||
|
name: "CAC3 Mainnet"
|
||||||
|
ticker: "CAC3"
|
||||||
|
site_url: "https://explorer.example.com"
|
||||||
|
# Decimal places for coin amounts. CAC3 follows Bitcoin's 8.
|
||||||
|
coin_decimals: 8
|
||||||
|
# Block time target in seconds (used for ETA / hashrate estimates).
|
||||||
|
block_time_seconds: 10
|
||||||
|
|
||||||
|
# Public-facing links shown in the header. Leave empty strings to hide.
|
||||||
|
links:
|
||||||
|
website: "https://cac3.example.com"
|
||||||
|
github: "https://github.com/SamiAhmed7777/cac3"
|
||||||
|
# Optional: deep-link tx / address / block pages to another explorer
|
||||||
|
# (e.g. if you want a sister explorer for a sister chain)
|
||||||
|
# alt_explorer: "https://alt-explorer.example.com"
|
||||||
|
|
||||||
|
# Cache layer (in-memory by default). Set redis_url to share cache across replicas.
|
||||||
|
cache:
|
||||||
|
backend: "memory" # "memory" | "redis"
|
||||||
|
ttl: "30s"
|
||||||
|
# redis_url: "redis://127.0.0.1:6379/0"
|
||||||
|
|
||||||
|
# UI
|
||||||
|
ui:
|
||||||
|
# Set false to disable the "Search" box (e.g. if fronted by an external search)
|
||||||
|
show_search: true
|
||||||
|
# Page footer copyright
|
||||||
|
footer: "© 2026 CAC3 Project"
|
||||||
Reference in New Issue
Block a user