Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: Validate explorer

on:
pull_request:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true

jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version-file: .node-version
- uses: oven-sh/setup-bun@v2
with:
bun-version: 1.4.4
- run: bun install --frozen-lockfile
- run: bun run lint
- run: bun run test
- run: bun run lint:type
- run: bun run build
73 changes: 0 additions & 73 deletions .github/workflows/nuxtjs.yml

This file was deleted.

1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,6 @@ node_modules
dist
.DS_Store
.vercel
.build
src/graphql
src/public/font
1 change: 1 addition & 0 deletions .node-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
24.15.0
92 changes: 84 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,17 @@
# Bitcoin Cash Explorer

Nuxt 3 explorer with CashTokens, address tools, and transaction analytics.
Nuxt 4 explorer with CashTokens, address tools, and transaction analytics.

## Development

Use Bun **1.4.4** and Node **24.15.0+** (the supported LTS line is pinned in
`.node-version`). Node must satisfy the `engines` range in `package.json`.
Bun is the package manager for local work, CI, and Cloudflare; commit `bun.lock`
when dependencies change. Do not generate npm or pnpm lockfiles.

```bash
pnpm install --frozen-lockfile
pnpm dev
bun install --frozen-lockfile
bun run dev
```

The default data source is `gql.chaingraph.pat.mn`, matching the configured
Expand All @@ -33,23 +38,89 @@ The Settings page includes these public gateway options:
The selected gateway is stored in the browser and overrides the deployment
default for that browser.

## Transaction token badges

Transaction input/output badges use compact **display** amounts: `2000` becomes
`2k`. Amounts below 1000 retain every decimal; larger amounts use up to three
significant digits with `k`, `m`, `b`, or `t` (scientific notation from `10^15`).
`≈` marks rounding, including rounding up into the next suffix. BCMR token
decimals are applied before compaction using arbitrary-precision arithmetic.
Until metadata is available, the amount is shown in base units and identified
as such in its exact-value disclosure.

Long NFT commitments show the first seven and last eight characters, separated
by `......`; values of 21 characters or fewer stay intact, including leading zeros.
Tap/click an amount or commitment, or focus it and press Enter/Space, to inspect
and copy the full exact value. Token disclosures also include the original
on-chain base units when they differ. Titles and accessible labels contain the
exact value. Compact text is never used for copying or on-chain operations;
other full-value tables and details keep their existing exact-display behavior.

## Generated assets

`bun install` generates the typed GraphQL documents and prepares Nuxt. The checked-in
`schema/chaingraph.graphql` snapshot makes installation, typechecking, and builds
independent of the live indexer's availability. Generated files in `src/graphql`
and icon fonts in `src/public/font` are ignored; the Vite plugins regenerate them
for development and production builds.

After changing a GraphQL operation, run `bun run codegen` (also run automatically
by `lint:type` and Vite). To deliberately update the schema from the configured
Chaingraph endpoint, run `bun run schema:pull` and review the snapshot diff.
Use `bun run icons` to regenerate the icon font manually.

## Dependency maintenance

This project uses Nuxt 4, Vue 3, Vue Router 5, Pinia 4, Tailwind 4, and Biome 2.
Tailwind configuration lives in `src/assets/css/main.css` and runs through the
Vite plugin. Biome checks Vue templates and scripts; `bun run lint` is read-only
and `bun run lint:fix` applies safe formatting and fixes.

Two packages intentionally use the latest compatible release:

- TypeScript **6.0.3**: `vue-tsc` currently requires the JavaScript compiler entry
point that TypeScript 7 no longer exports.
- GraphQL **16.15.0**: Nuxt Apollo's current Nuxt-compatible release
(`5.0.0-alpha.16`) depends on Apollo Client 3 and GraphQL 16. The package's
`latest` dist-tag points to the older Nuxt 2 module, so it is pinned explicitly.

The deprecated `electrum-cash` dependency has been replaced by
`@electrum-cash/network`; balance and history responses are validated with Valibot.
A scoped Undici 6 override patches the icon-generation toolchain without changing
Nuxt's or Wrangler's newer Undici major versions.

`bun audit` currently reports three upstream build-tool advisories: `deepmerge`
(low, no patched release), and `glob` / `minimatch` (moderate, older major ranges
required by their consumers). No high or critical advisories remain. Recheck these
when updating the toolchain; do not force incompatible transitive major versions.

## Verification and deployment

```bash
pnpm lint:type
pnpm generate
wrangler deploy --dry-run
wrangler deploy
bun run lint
bun run test
bun run lint:type
bun run build
bunx wrangler deploy --dry-run
bunx wrangler deploy
```

Wrangler runs a fresh static build and uploads `.output/public` to the `explorer`
Worker, with SPA routing for address, transaction, block, and token URLs.
The configured custom domain is `explorer.salemkode.com`.

Use Wrangler 4 and authenticate with `wrangler login` before deploying.
Wrangler 4 is installed with the project. Authenticate with
`bunx wrangler login` before deploying.
The Cloudflare account must manage the `salemkode.com` zone. An existing DNS record
for the custom domain may need replacement when moving from another host.

The GitHub Actions workflow runs a frozen install, lint, regression tests,
typechecking, and a static build on pull requests and `main`. Cloudflare owns
deployments; the obsolete GitHub Pages deployment has been removed.

The existing Netlify preview integration uses the same static build through
`netlify.toml`, with explicit Node/Bun versions and SPA redirects.

## Automatic GitHub deployments

Cloudflare Workers Builds is connected to `salemkode/explorer`:
Expand All @@ -72,3 +143,8 @@ View visits, page views, referrers, and performance in the Cloudflare account's
**Analytics → Web Analytics → explorer.salemkode.com** dashboard. The beacon token
is a public site identifier, not an API credential. Future builds retain the
tracking script automatically.

The compact badge suite also retains issue #26's exact-value regressions, including
`72624976668144285` and the maximum fungible amount. Its disclosure and copy-value
assertions replace the earlier raw-only text snapshots because compact labels
and registry decimal scaling intentionally change the visible summary.
36 changes: 28 additions & 8 deletions biome.json
Original file line number Diff line number Diff line change
@@ -1,14 +1,34 @@
{
"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
"files": {
"ignore": [
"src/graphql",
"src/public",
".*",
"node_modules",
"dist",
".output",
".nuxt"
"includes": [
"**",
"!!**/node_modules",
"!!**/.nuxt",
"!!**/.output",
"!!**/.build",
"!!src/graphql",
"!!src/public",
"!!src/assets/icons",
"!!src/assets/images",
"!src/assets/bcmr-v2.schema.json",
"!schema/chaingraph.graphql"
]
},
"vcs": {
"enabled": true,
"clientKind": "git",
"useIgnoreFile": true
},
"css": {
"parser": {
"tailwindDirectives": true
}
},
"html": {
"experimentalFullSupportEnabled": true,
"formatter": {
"enabled": false
}
}
}
Loading
Loading