From a91aa976ceace0fe8280e5e261f1a586154dee63 Mon Sep 17 00:00:00 2001 From: mhaines Date: Fri, 13 Feb 2026 17:00:48 -0500 Subject: [PATCH 1/3] Add CLAUDE.md with build, test, and project reference Comprehensive project reference covering build instructions (macOS/Linux), all scripts, project layout, code style conventions, path aliases, CI pipeline, key Seismic concepts, and troubleshooting. Every documented command was verified on the current machine. --- CLAUDE.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..2701eaf1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,158 @@ +# Seismic Client + +Bun monorepo containing TypeScript client libraries for the [Seismic blockchain](https://seismic.systems) — a privacy-focused EVM chain that encrypts transaction calldata using AEAD (AES-GCM). The two published npm packages are **seismic-viem** (viem extensions) and **seismic-react** (wagmi-compatible React hooks). + +## Build + +Requires **Bun >=1.2.5** and **Node >=16**. + +### macOS + +```bash +brew install oven-sh/bun/bun # or: curl -fsSL https://bun.sh/install | bash +bun install +bun run all:build # builds seismic-viem, seismic-react, seismic-viem-tests +``` + +### Linux (Ubuntu) + +```bash +curl -fsSL https://bun.sh/install | bash +bun install +bun run all:build +``` + +### Verify + +```bash +ls packages/seismic-viem/dist/_cjs/index.js packages/seismic-react/dist/_esm/index.js +# Both files should exist +``` + +### Individual package builds + +```bash +bun run viem:build # packages/seismic-viem (CJS + ESM + types) +bun run react:build # packages/seismic-react (CJS + ESM + types) +bun run tests:build # packages/seismic-viem-tests (ESM + types) +``` + +## Checks + +```bash +bun run check # typecheck + lint (runs everything below) +bun run typecheck # tsc --noEmit on seismic-viem then seismic-react +bun run lint:check # eslint + prettier (no auto-fix) +bun run lint # eslint + prettier (with auto-fix) +``` + +Note: `react:typecheck` rebuilds seismic-viem first (it depends on the built types). + +## Tests + +### Integration tests (require external tooling) + +Tests live in `tests/seismic-viem/` and require a running Seismic node. Two modes: + +```bash +bun run viem:test:anvil # CHAIN=anvil — needs sanvil (from sfoundryup) +bun run viem:test:reth # CHAIN=reth — needs seismic-reth binary +``` + +**Anvil tests** require `SFOUNDRY_ROOT` env var pointing to a [seismic-foundry](https://github.com/SeismicSystems/seismic-foundry) checkout (with Rust/Cargo installed), OR the `sanvil` binary in PATH. If `SFOUNDRY_ROOT` is set, the test harness builds sanvil from source via `cargo build --bin sanvil`. + +**Reth tests** require `SRETH_ROOT` pointing to a [seismic-reth](https://github.com/SeismicSystems/seismic-reth) checkout. + +### Solidity tests (Foundry) + +```bash +git submodule update --init --recursive # first time only +sforge test --root contracts +``` + +Requires `sforge` (installed via [sfoundryup](https://github.com/SeismicSystems/seismic-foundry)). Runs 16 tests across 3 test suites (SeismicCounter, TransparentCounter, ShieldedDelegationAccount). + +### Docs + +```bash +bun run docs:dev # local dev server +bun run docs:build # production build (VoCs) +bun run docs:preview # preview production build +``` + +## Project Layout + +``` +packages/ + seismic-viem/ Core viem extensions (npm: seismic-viem@1.1.1) + src/ + chain.ts Chain definitions (sanvil, seismicTestnet, localSeismicDevnet) + client.ts createShieldedPublicClient, createShieldedWalletClient + sendTransaction.ts Seismic transaction sending + contract/ getShieldedContract, shieldedWriteContract, signedReadContract + crypto/ AES-GCM, ECDH, HKDF, nonce generation, AEAD + precompiles/ On-chain precompile wrappers (rng, ecdh, hkdf, aes, secp256k1) + actions/ Deposit contract, SRC20 token support + abis/ SRC20, deposit contract, directory ABIs + seismic-react/ React hooks (npm: seismic-react@1.1.1) + src/ + context/ ShieldedWalletProvider + hooks/ useShieldedWriteContract, useSignedReadContract, useShieldedContract + rainbowkit/ RainbowKit integration + seismic-viem-tests/ Shared test utilities (npm: seismic-viem-tests@0.1.4) + src/ + process/ Node process management (anvil, reth spawn/kill) + tests/ Reusable test functions (contract, precompiles, encoding, etc.) + seismic-bot/ Slack bot for faucet management (internal) + seismic-spammer/ Transaction load testing tool (internal) +tests/ + seismic-viem/ Integration test runner (bun test) +contracts/ Solidity contracts (Foundry) + src/ SeismicCounter, TransparentCounter, SRC20, DepositContract + test/ Foundry tests (.t.sol) + lib/ Git submodules (forge-std, openzeppelin, solady) +docs/ Documentation site (VoCs + Tailwind) +``` + +## Code Style + +**Prettier** (enforced): 2-space indent, single quotes, no semicolons, 80-char width, trailing commas (ES5). Import sorting via `@trivago/prettier-plugin-sort-imports` with groups: types → external → relative (separated by blank lines). + +**ESLint** (enforced): No relative import paths (`no-relative-import-paths` plugin), no unused imports. TypeScript-aware via `@typescript-eslint` with project service. + +**TypeScript path aliases** — each package uses aliases instead of relative imports: + +- `@sviem/*` → `seismic-viem/src/*` +- `@sreact/*` → `seismic-react/src/*` +- `@sviem-tests/*` → `seismic-viem-tests/src/*` + +These are resolved at build time by `tsc-alias`. + +## CI + +GitHub Actions (`.github/workflows/ci.yml`): + +- **lint**: ESLint + Prettier on ubuntu-24.04 (Bun 1.2.5) +- **typecheck**: tsc on ubuntu-24.04 +- **test-anvil**: Self-hosted runner, builds sanvil from `SFOUNDRY_ROOT`, runs anvil tests +- **test-devnet**: Self-hosted runner (after test-anvil), builds seismic-reth, runs reth tests + +## Key Concepts + +- **Seismic TX type** (`0x4a` / 74): Custom transaction type with encryption fields (pubkey, nonce, messageVersion, recentBlockHash, expiresAtBlock, signedRead) +- **Shielded clients**: Wrappers around viem clients that handle ECDH key exchange with the node and AES-GCM encryption of calldata +- **SRC20**: Seismic's shielded ERC20 variant with encrypted transfer logs +- **Precompiles**: On-chain crypto primitives at addresses `0x64`–`0x69` (RNG, ECDH, HKDF, AES-GCM encrypt/decrypt, secp256k1) +- **Chain ID**: 5124 (testnets), 31337 (local anvil) + +## Troubleshooting + +| Problem | Fix | +| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `SFOUNDRY_ROOT env variable must be set to build sanvil` | Set `SFOUNDRY_ROOT` to your seismic-foundry repo path, or install `sanvil` via `sfoundryup` and modify the test to skip the build step | +| `ENOENT: posix_spawn 'cargo'` when running tests | `SFOUNDRY_ROOT` is set but Cargo/Rust is not installed. Either install Rust (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh`) or unset `SFOUNDRY_ROOT` if `sanvil` is already in PATH | +| `forge` / `sforge` not found for Solidity tests | Install via `sfoundryup`: `curl -L https://raw.githubusercontent.com/SeismicSystems/seismic-foundry/seismic/sfoundryup/install \| bash && sfoundryup` | +| `git submodule` dirs empty (contracts/lib/) | Run `git submodule update --init --recursive` | +| `react:typecheck` fails with missing types | Run `bun run viem:build` first — react typecheck depends on built viem types | +| `Browserslist: browsers data is X months old` on docs build | Harmless warning. Fix with `npx update-browserslist-db@latest` if desired | +| `hideExternalIcon` React prop warning during docs build | Harmless VoCs warning — safe to ignore | From 19156e979040d3483363ac5f1befe558ddd0e76f Mon Sep 17 00:00:00 2001 From: Christian Drappi Date: Tue, 24 Feb 2026 14:36:53 -0500 Subject: [PATCH 2/3] cleanup claude md --- CLAUDE.md | 25 +++++++++---------------- 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2701eaf1..9ea014af 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,22 +4,12 @@ Bun monorepo containing TypeScript client libraries for the [Seismic blockchain] ## Build -Requires **Bun >=1.2.5** and **Node >=16**. - -### macOS - -```bash -brew install oven-sh/bun/bun # or: curl -fsSL https://bun.sh/install | bash -bun install -bun run all:build # builds seismic-viem, seismic-react, seismic-viem-tests -``` - -### Linux (Ubuntu) +Requires **Bun >=1.2.5**. ```bash curl -fsSL https://bun.sh/install | bash bun install -bun run all:build +bun run all:build # builds seismic-viem, seismic-react, seismic-viem-tests ``` ### Verify @@ -116,9 +106,11 @@ docs/ Documentation site (VoCs + Tailwind) ## Code Style -**Prettier** (enforced): 2-space indent, single quotes, no semicolons, 80-char width, trailing commas (ES5). Import sorting via `@trivago/prettier-plugin-sort-imports` with groups: types → external → relative (separated by blank lines). +**Prettier** (`.prettierrc.json`): 2-space indent, single quotes, no semicolons, 80-char width, trailing commas (ES5). Import sorting via `@trivago/prettier-plugin-sort-imports` with groups: types → external → relative (separated by blank lines). + +**ESLint** (`eslint.config.cjs`): No relative import paths (`no-relative-import-paths` plugin), no unused imports. TypeScript-aware via `@typescript-eslint` with project service. -**ESLint** (enforced): No relative import paths (`no-relative-import-paths` plugin), no unused imports. TypeScript-aware via `@typescript-eslint` with project service. +**TypeScript** (`tsconfig.base.json`, `tsconfig.json`): Shared base config with strict mode, NodeNext module resolution, ES2021 target. Each package extends the base and defines its own path aliases. **TypeScript path aliases** — each package uses aliases instead of relative imports: @@ -135,7 +127,7 @@ GitHub Actions (`.github/workflows/ci.yml`): - **lint**: ESLint + Prettier on ubuntu-24.04 (Bun 1.2.5) - **typecheck**: tsc on ubuntu-24.04 - **test-anvil**: Self-hosted runner, builds sanvil from `SFOUNDRY_ROOT`, runs anvil tests -- **test-devnet**: Self-hosted runner (after test-anvil), builds seismic-reth, runs reth tests +- **test-devnet**: Self-hosted runner (after test-anvil), builds seismic-reth from `SRETH_ROOT`, runs reth tests ## Key Concepts @@ -143,13 +135,14 @@ GitHub Actions (`.github/workflows/ci.yml`): - **Shielded clients**: Wrappers around viem clients that handle ECDH key exchange with the node and AES-GCM encryption of calldata - **SRC20**: Seismic's shielded ERC20 variant with encrypted transfer logs - **Precompiles**: On-chain crypto primitives at addresses `0x64`–`0x69` (RNG, ECDH, HKDF, AES-GCM encrypt/decrypt, secp256k1) -- **Chain ID**: 5124 (testnets), 31337 (local anvil) +- **Chain ID**: 5124 (testnet), 31337 (local anvil) ## Troubleshooting | Problem | Fix | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SFOUNDRY_ROOT env variable must be set to build sanvil` | Set `SFOUNDRY_ROOT` to your seismic-foundry repo path, or install `sanvil` via `sfoundryup` and modify the test to skip the build step | +| `SRETH_ROOT env variable must be set to build reth` | Set `SRETH_ROOT` to your seismic-reth repo path (with Rust/Cargo installed) | | `ENOENT: posix_spawn 'cargo'` when running tests | `SFOUNDRY_ROOT` is set but Cargo/Rust is not installed. Either install Rust (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh`) or unset `SFOUNDRY_ROOT` if `sanvil` is already in PATH | | `forge` / `sforge` not found for Solidity tests | Install via `sfoundryup`: `curl -L https://raw.githubusercontent.com/SeismicSystems/seismic-foundry/seismic/sfoundryup/install \| bash && sfoundryup` | | `git submodule` dirs empty (contracts/lib/) | Run `git submodule update --init --recursive` | From 870cbfa652e4663b3873bc258899fa11fa98a43c Mon Sep 17 00:00:00 2001 From: Christian Drappi Date: Tue, 24 Feb 2026 14:37:48 -0500 Subject: [PATCH 3/3] Fix formatting and clarify installation instructions --- CLAUDE.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9ea014af..00231392 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,9 +7,11 @@ Bun monorepo containing TypeScript client libraries for the [Seismic blockchain] Requires **Bun >=1.2.5**. ```bash +# If bun is not installed already: curl -fsSL https://bun.sh/install | bash -bun install -bun run all:build # builds seismic-viem, seismic-react, seismic-viem-tests + +bun install # install dependencies +bun run all:build # builds seismic-viem, seismic-react, seismic-viem-tests ``` ### Verify