+
+
```
-See [Using E-Components](/contributing/e-components) for the full API reference.
+The `useStandardPrecompileRun` helper covers the common EthereumJS pre/post hardfork comparison. For custom execution (different library, custom precompile, etc.), provide your own `run` function and `#result` slot — see [Available E-Components](/contributing/available-e-components) for the full API reference.
## Step 5: Register in the Registry
@@ -204,7 +227,99 @@ Import libraries only in your `MyC.vue` — never in shared code. This keeps eac
If you need a custom library fork (e.g. with experimental features), see [Library Forks](/contributing/library-forks).
-## Step 7: Verify
+## Step 7: Add Tests
+
+Each exploration should have a `tests.spec.ts` file in its folder. Tests verify that your exploration's metadata, examples, and config are correct.
+
+### What to Test
+
+**All explorations** should test:
+
+- `info.ts` — correct `id`, `path`, `topic`, and `poweredBy`
+- `examples.ts` — each example has the right number of values, valid hex data, and a non-empty title
+
+**Precompile explorations** should additionally test:
+
+- `config.ts` — `defaultExample` exists in examples, value field count and URL params match expectations
+- `assembleData`/`parseData` — if defined, verify they produce correct output and are inverse operations
+
+### Example: Custom Exploration Test
+
+```typescript
+import { describe, expect, it } from 'vitest'
+
+import { examples } from '../examples'
+import { INFO } from '../info'
+
+describe('EIP-XXXX Exploration', () => {
+ describe('info', () => {
+ it('has correct metadata', () => {
+ expect(INFO.id).toBe('eip-XXXX')
+ expect(INFO.path).toContain('eip-XXXX')
+ expect(INFO.topic).toBe('fusaka')
+ expect(INFO.poweredBy.length).toBeGreaterThan(0)
+ })
+ })
+
+ describe('examples', () => {
+ it('each example has valid hex data', () => {
+ const hexRegex = /^[0-9a-f]+$/i
+ for (const [key, ex] of Object.entries(examples)) {
+ for (const val of ex.values) {
+ expect(val, `Value in "${key}" should be valid hex`).toMatch(hexRegex)
+ }
+ }
+ })
+ })
+})
+```
+
+### Example: Precompile Exploration Test
+
+```typescript
+import { describe, expect, it } from 'vitest'
+
+import { config } from '../config'
+import { examples } from '../examples'
+import { INFO } from '../info'
+
+describe('EIP-XXXX Exploration', () => {
+ describe('info', () => {
+ it('has correct metadata', () => {
+ expect(INFO.id).toBe('eip-XXXX')
+ expect(INFO.topic).toBe('fusaka')
+ })
+ })
+
+ describe('config', () => {
+ it('references a valid default example', () => {
+ expect(examples[config.defaultExample]).toBeDefined()
+ })
+
+ it('has correct number of value fields', () => {
+ expect(config.values).toHaveLength(2)
+ })
+ })
+
+ describe('examples', () => {
+ it('each example has the right number of values', () => {
+ const editableCount = config.values.filter((v) => v.urlParam).length
+ for (const [key, ex] of Object.entries(examples)) {
+ expect(ex.values, `Example "${key}"`).toHaveLength(editableCount)
+ }
+ })
+ })
+})
+```
+
+### Running Tests
+
+```bash
+npx vitest run # run all unit tests
+npx vitest run src/explorations/eip-XXXX # run tests for one exploration
+```
+
+## Step 8: Verify
```bash
npm run dev # check your exploration locally
@@ -218,7 +333,9 @@ npm run build # verify production build
- [ ] Created `src/explorations//info.ts` with metadata
- [ ] Created `src/explorations//MyC.vue` with interactive widget
- [ ] Created `src/explorations//examples.ts` with example presets
+- [ ] Created `src/explorations//tests.spec.ts` with unit tests
- [ ] Added import and entry in `src/explorations/REGISTRY.ts`
- [ ] Installed library dependencies (if needed)
+- [ ] All unit tests pass
- [ ] Linting and type checking pass
- [ ] Production build succeeds
diff --git a/docs/contributing/available-e-components.md b/docs/contributing/available-e-components.md
index fe57124..6ab727d 100644
--- a/docs/contributing/available-e-components.md
+++ b/docs/contributing/available-e-components.md
@@ -4,47 +4,49 @@ This page lists all E-Components that are ready to use in your explorations. For
## Precompile Interface (`precompileInterfaceEC`)
-A complete interface for exploring EVM precompiles. It handles:
+An interface for exploring EVM precompiles. It handles input management while leaving execution and result display to the exploration:
- Example selection and URL sharing
- Hex data input with parsing and validation
- Individual value inputs with byte length tracking
-- Side-by-side pre/post hardfork comparison (running the precompile on two different EVM versions)
-- Result display with gas cost and output data
+- **Execution and result display** are provided by the exploration via the `run` prop and `#result` slot
**Files:**
```
src/eComponents/precompileInterfaceEC/
├── PrecompileInterfaceEC.vue # Main component
-├── PrecompileInterfaceResultEC.vue # Result display (pre/post comparison)
+├── PrecompileInterfaceResultEC.vue # Result display (reusable, e.g. pre/post comparison)
├── PrecompileValueInputEC.vue # Value input with byte length validation
-├── usePrecompileState.ts # Composable: all state and logic
+├── usePrecompileState.ts # Composable: input state and sync logic
├── types.ts # PrecompileConfig and PrecompileValueDef
-└── run.ts # EVM precompile execution utility
+└── run.ts # EVM precompile execution utility + useStandardPrecompileRun
```
**Used by:** [EIP-7951](https://github.com/feelyourprotocol/website/blob/main/src/explorations/eip-7951/MyC.vue) (secp256r1), [EIP-7883](https://github.com/feelyourprotocol/website/blob/main/src/explorations/eip-7883/MyC.vue) (ModExp gas cost)
### Basic Usage
-A precompile exploration needs just a config object and a single component tag:
+A precompile exploration provides a config for input layout, a `run` function for execution, and a `#result` slot for visualization. For the standard EthereumJS pre/post hardfork comparison, use the `useStandardPrecompileRun` helper:
```vue
-
+
+
+
+
+
+
+
+
```
+### Component Props
+
+| Prop | Required | Description |
+|------|----------|-------------|
+| `config` | Yes | Input configuration (see `PrecompileConfig` below) |
+| `examples` | Yes | Example presets from `examples.ts` |
+| `exploration` | Yes | Exploration metadata from `info.ts` |
+| `run` | Yes | Execution function, called with the assembled hex data (without `0x`) on every valid input change |
+
### `PrecompileConfig` Reference
```typescript
interface PrecompileConfig {
explorationId: string
- precompileAddress: string
- preHardfork: Hardfork
- postHardfork: Hardfork
defaultExample: string
showBigInt?: boolean
values: PrecompileValueDef[]
@@ -77,9 +94,6 @@ interface PrecompileConfig {
| Field | Required | Description |
|-------|----------|-------------|
| `explorationId` | Yes | Matches the exploration's `id` in `info.ts` |
-| `precompileAddress` | Yes | Hex address of the precompile (e.g. `'05'` for ModExp) |
-| `preHardfork` | Yes | Hardfork for the "before" comparison |
-| `postHardfork` | Yes | Hardfork for the "after" comparison |
| `defaultExample` | Yes | Key from `examples.ts` to load on initialization |
| `showBigInt` | No | Show BigInt representations for values (default: per-value setting) |
| `values` | Yes | Array of value definitions (see below) |
@@ -137,3 +151,62 @@ const config: PrecompileConfig = {
},
}
```
+
+### Execution: `run` Prop and `#result` Slot
+
+The E-Component separates input management from execution. The exploration provides:
+
+1. A **`run` function** — called automatically with the assembled hex data on every valid input change
+2. A **`#result` slot** — renders the execution results however the exploration needs
+
+#### Standard: `useStandardPrecompileRun`
+
+For the common pre/post hardfork comparison using the EthereumJS EVM, use the provided helper:
+
+```typescript
+import { useStandardPrecompileRun } from '@/eComponents/precompileInterfaceEC/run'
+
+const { run, execResultPre, execResultPost } = useStandardPrecompileRun(
+ Hardfork.Prague, Hardfork.Osaka, '05',
+)
+```
+
+This returns a `run` function ready to pass as a prop and two reactive refs for the results. Use `PrecompileInterfaceResultEC` in the `#result` slot for the standard gas + hex display.
+
+#### Custom Execution
+
+For explorations that need a different execution mechanism (custom precompile, different library, etc.), define your own `run` function and result state:
+
+```vue
+
+
+
+
+
+
+
+
{{ myResult }}
+
Press enter or change input...
+
+
+
+
+
+```
+
+The `#result` slot template lives in the exploration's scope, so it naturally accesses your own refs and computed properties.
diff --git a/docs/contributing/styling.md b/docs/contributing/styling.md
index 3a5fb13..5a77015 100644
--- a/docs/contributing/styling.md
+++ b/docs/contributing/styling.md
@@ -4,7 +4,7 @@ The project uses [Tailwind CSS v4](https://tailwindcss.com/) for styling with a
## How Topic Colors Work
-Every exploration belongs to a **topic** (e.g. "Fusaka"), and each topic has a color (blue, yellow, green, red). The `ExplorationC` wrapper component sets CSS custom properties on its root element based on the topic color. All child components — UI components, E-Components, and your widget — automatically inherit these colors.
+Every exploration belongs to a **topic** (e.g. "Fusaka"), and each topic has a color (blue, yellow, green, red, orange, purple). The `ExplorationC` wrapper component sets CSS custom properties on its root element based on the topic color. All child components — UI components, E-Components, and your widget — automatically inherit these colors.
```
Topic (e.g. Fusaka = blue)
@@ -20,13 +20,14 @@ These variables are set by `ExplorationC` and available to all child elements:
| Variable | Purpose | Blue topic example |
|----------|---------|-------------------|
-| `--e-text` | Primary text color | `blue-900` |
-| `--e-bg` | Exploration wrapper background | `blue-200` |
-| `--e-bg-light` | Input backgrounds | `blue-50` |
+| `--e-text` | Primary text color | `blue-800` |
+| `--e-bg` | Exploration wrapper background | `blue-100` |
+| `--e-bg-light` | Input backgrounds | `white` |
| `--e-bg-medium` | Button backgrounds | `blue-100` |
| `--e-bg-dark` | Result box backgrounds | `blue-900` |
-| `--e-border` | Light borders | `blue-200` |
-| `--e-border-dark` | Dark borders | `blue-900` |
+| `--e-border` | Borders on coloured backgrounds | `blue-300` |
+| `--e-border-dark` | Dark/emphasis borders | `blue-800` |
+| `--e-accent` | Focus rings, interactive accents | `blue-600` |
If you need the topic color for custom elements, use the `.e-text` utility class or reference the variables directly:
diff --git a/src/eComponents/precompileInterfaceEC/PrecompileInterfaceEC.vue b/src/eComponents/precompileInterfaceEC/PrecompileInterfaceEC.vue
index 6511333..c2606b9 100644
--- a/src/eComponents/precompileInterfaceEC/PrecompileInterfaceEC.vue
+++ b/src/eComponents/precompileInterfaceEC/PrecompileInterfaceEC.vue
@@ -1,4 +1,6 @@
-
@@ -62,10 +67,7 @@ await init()
:bigIntVal="bigIntVals[val.index]"
/>
-